Take GitLab to the Command Line

#git #gitlab #contributorswanted

This guide features glab, an open-source GitLab CLI tool I maintain.

In this quickstart guide, you’ll learn glab: find out what the tool is used for, how to set it up, and how to use it.

If you’re a GitLab user, you’re obviously aware that you need to switch to the web browser in order to perform various actions like creating issues, merge requests, viewing pipeline logs, etc on your GitLab repository.
With the glab, you can execute many of these actions without leaving the command-line interface.

Setting up `glab`

To get started, simply visit the installation page and find instructions on how to install glab for your operating system.

glab can be installed via several package managers such as homebrew for macOS, Scoop for Windows, and other platform-specific package managers for Linux including Snapcraft.

Below are snapshots of installation instructions for each supported platform:

Windows:



$ scoop install glab

macOS:



$ brew install glab

Linux

SnapCraft

Make sure you have snap installed on your Linux Distro (https://snapcraft.io/docs/installing-snapd).



$ sudo snap install --edge glab
$ sudo snap connect glab:ssh-keys

Debian/Ubuntu Linux:



$ sudo apt install git && sudo dpkg -i glab_*_linux_amd64.deb

Fedora/Centos Linux:



$ sudo yum localinstall glab_*_linux_amd64.rpm

Arch Linux:

glab is available through the gitlab-glab-bin and gitlab-glab packages on the AUR



$ yay -S gitlab-glab

or with pacman



$ sudo pacman -S gitlab-glab-bin

KISS Linux:

glab is available on the KISS Linux Community Repo as gitlab-glab. If you already have the community repo configured in your KISS_PATH you can install glab through your terminal:



$ kiss b gitlab-glab && kiss i gitlab-glab

Authentication

After installing glab, you’ll need to authenticate your account with a Personal Access Token.

Get a GitLab access token at https://gitlab.com/profile/personal_access_tokens or https://gitlab.example.com/profile/personal_access_tokens if it is a self-hosted instance and run:



$ glab auth login

This starts an interactive set-up like the screenshot below:

There are other authentication options for non-interactive mode:

authenticate against gitlab.com by reading the token from a file ```sh

$ glab auth login --stdin < myaccesstoken.txt


 - authenticate against a self-hosted GitLab instance by reading from a file
```sh


$ glab auth login --hostname salsa.debian.org --stdin < myaccesstoken.txt

authenticate with token and hostname (Not recommended for shared environments) ```sh

$ glab auth login --hostname gitlab.example.org --token xxxxx



# [`glab`](https://github.com/profclems/glab) Core Commands

[`glab`](https://github.com/profclems/glab) provides these core commands to interact with GitLab API and repositories
```sh


  alias:       Create, list and delete aliases
  api:         Make an authenticated request to GitLab API
  auth:        Manage glab{% raw %}`s authentication state
  check-update: Check for latest glab releases
  completion:  Generate shell completion scripts
  config:      Set and get glab settings
  help:        Help about any command
  issue:       Work with GitLab issues
  label:       Manage labels on remote
  mr:          Create, view and manage merge requests
  pipeline:    Manage pipelines
  release:     Manage GitLab releases
  repo:        Work with GitLab repositories and projects
  user:        Interact with user
  version:     show glab version information

```

Each core command has nested/child commands where you can specify the operation you want to perform — such as `glab repo clone` or `glab issue list`. 

We’ll look at some of the commands in more detail in the upcoming sections.


# Repository Commands

Cloning a repo with the `glab` is easier than using the git command. To clone, all you have to do is execute the command in the following format:

```sh
$ glab repo clone NAMESPACE/REPO
```
To clone your own repository, save yourself time by omitting the `NAMESPACE`.
You no longer need to copy the clone url before cloning a repository:
```
$ glab repo clone glab-cli/test
```
`glab` will clone using your preferred `git_protocol` set during authentication or you can set/update with:
```sh
$ glab config set --global git_protocol {ssh | https}
```
Specify `--host` flag to make it host-specific.


You can also download an archive of an existing repository easily from the command line. Try:
```sh
$ glab repo archive profclems/glab --format tar.gz
```
The `--format` flag allows you to specify the format in which you want the archive downloaded. 
Supports formats: `{tar.gz | tar.bz2 | tbz | tbz2 | tb2 | bz2 | tar | zip}`

You can also create a new GitLab repository from the command line. Assuming you have a local git repository or project you would want to create a new GitLab repository from, just `cd` into the project root directory and run:

```sh
$ glab repo create --public
```
If you don’t specify the --public option, a private repository will be created by default. 
If you’d like to create the repo under a different namespace, you’ll need to use the following syntax: `glab repo create namespace/repo`

# Merge Requests and Issues Workflow
Creating an issue, working on the issue and creating a merge request for your team to review can now be done on the terminal interactively with `glab mr create`.

`glab` supports issue and merge request templates and allows you to select the template to apply and edit. It automatically loads and caches the project labels and opens the multiselect prompt to select the labels to add.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/fm59bb741cwpg5xyfv5m.png)

Below is the full output
```sh
$ glab mr create
? Choose a template  [Use arrows to move, type to filter]
> Default
  Open a blank merge request

? Description <Received>
? Do you want to add labels? Yes
? Select Labels  [Use arrows to move, space to select, <right> to all, <left> to none, type to filter]
> [ ]  Doing
  [x]  To Do
  [x]  bug
  [ ]  frontend
  [ ]  label1
  [ ]  label2
  [ ]  none

Creating merge request for fix-ci-br into (master) in glab-cli/test

!1 CI failure occured (fix-ci-br)
 https://gitlab.com/glab-cli/test/-/merge_requests/1

```

You can also create a merge request for an issue as done on the GitLab UI from the command line with:
```sh
$ glab mr for <issueID>
```
This is create a new draft merge request for the issue and also create a new branch using the title of the issue.

Assuming our first issue has the title "CI failure occurred":

```sh
→ glab mr for 1

!2 Draft: Resolve "CI failure occurred" (1-ci-failure-occurred)
 https://gitlab.com/glab-cli/test/-/merge_requests/2

```
You can then checkout to the merge request branch with `glab mr checkout <id>`

```sh
$ glab mr checkout 2
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 198 bytes | 2.00 KiB/s, done.
From gitlab.com:glab-cli/test
 * [new ref]         refs/merge-requests/2/head -> 1-ci-failure-occured

```

# Configuration

`glab` follows the XDG Base Directory [Spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html): global configuration file is saved at `~/.config/glab-cli`. Local configuration file is saved at the root of the working git directory and automatically added to `.gitignore`.

**To set configuration globally**

```sh
$ glab config set --global editor vim
```

**To set configuration for current directory (must be a git repository)**

```sh
$ glab config set editor vim
```

**To set configuration for a specific host**

Use the `--host` flag to set configuration for a specific host. This is always stored in the global config file with or without the `global` flag.

```sh
$ glab config set editor vim --host gitlab.example.org
```

# GitLab CI
The GitLab CI is a very important feature which comes as part of GitLab.

With `glab`, you no longer need to hop from IDE or command Line to the web to view job logs or watch the pipeline as it runs when you can easily do that from your command line.

`glab` provides `glab pipeline` command which has several nested commands to help you manage your GitLab CI environment. 
```sh
  ci:         Work with GitLab CI pipelines and jobs
  delete:     Delete a pipeline
  list:       Get the list of pipelines
  run:        Create a new pipeline run
  status:     View a running pipeline on current or other branch specified

```

You can watch the CI pipeline as it runs directly from your command line with `glab pipeline ci view` and trace job logs with `glab pipeline ci trace`

```sh
$ glab pipeline ci trace

Searching for latest pipeline on dev...
Getting jobs for pipeline 222781675...
? Select pipeline job to trace: deploy-staging (879211827) - success
Getting job trace...
Showing logs for deploy-staging job #879211827
Running with gitlab-runner 13.3.1 (738bbe5a)
  on Simeds Back-end CI Runner JyMs7scA
Preparing the "docker" executor
Using Docker executor with image ruby:2.5 ...
Pulling docker image ruby:2.5 ...
Using docker image 
....
....
Saving cache
Creating cache dev...
WARNING: vendor: no matching files                 
Created cache
Archive is up to date!                             
Job succeeded
```

# Conclusion

[`glab`](https://github.com/profclems/glab) offers a lot of core and subcommands that are very useful to GitLab users which we only looked at the basics. 
I would recommend you integrate the tool into your workflow and make it a habit, as it clearly does save some time managing your repository. 

Check the [documentation](glab.readthedocs.org) for all the commands available and their usage.

If you encounter any issue or want to suggest a feature, open an issue at https://github.com/profclems/glab/issues