Working with Gitlab on the CLI

Glab is an open-source tool that allows you to work with GitLab from the command line, eliminating the need to switch to a browser to create or approve merge requests, start a pipeline run, or view issues.

Glab can work with repositories hosted on gitlab.com as well as with your own GitLab instances. The tool automatically detects which instance it should work with.

The CLI tool was started by Clement Sam and has been an official GitLab product since 2022.

Setup

Glab can be installed in various ways. Since it is written in Golang, the executable can be easily downloaded and run from the releases page. Alternatively, Glab is also available in various package repositories. It runs on Linux, Windows, and macOS.

All installation options can be found here!

Registering with the GitLab Instance

Before working with repositories, you need to authenticate with the GitLab instance. For this, you need a Personal Access Token, which you can create in your GitLab profile. For the gitlab.com instance, you can create it here. Assign a name to the token and select the “api” and “write_repository” permissions. The generated token will be needed in the next step.

Now, log in to the GitLab instance using the token by running glab auth login and answering the prompts.

> glab auth login
? What GitLab instance do you want to log into? gitlab.com
- Logging into gitlab.com
? How would you like to login? Token

Tip: you can generate a Personal Access Token here https://gitlab.com/-/profile/personal_access_tokens
The minimum required scopes are 'api' and 'write_repository'.
? Paste your authentication token: **************************? Choose default git protocol HTTPS
? Authenticate Git with your GitLab credentials? Yes
- glab config set -h gitlab.com git_protocol https
✓ Configured git protocol
- glab config set -h gitlab.com api_protocol https
✓ Configured API protocol
✓ Logged in as rndmh3ro

You can verify a successful login with glab auth status.

> glab auth status
gitlab.com
  ✓ Logged in to gitlab.com as rndmh3ro (/home/segu/.config/glab-cli/config.yml)
  ✓ Git operations for gitlab.com configured to use https protocol.
  ✓ API calls for gitlab.com are made over https protocol
  ✓ REST API Endpoint: https://gitlab.com/api/v4/
  ✓ GraphQL Endpoint: https://gitlab.com/api/graphql/
  ✓ Token: **************************
git.example.com
  ✓ Logged in to git.example.com as segu (/home/segu/.config/glab-cli/config.yml)
  ✓ Git operations for git.example.com configured to use https protocol.
  ✓ API calls for git.example.com are made over https protocol
  ✓ REST API Endpoint: https://git.example.com/api/v4/
  ✓ GraphQL Endpoint: https://git.example.com/api/graphql/
  ✓ Token: **************************

Working with Repositories

Once successfully logged into the GitLab instance, you can work with repositories using glab.

Cloning a Repository

To clone repositories with glab, run glab repo clone path/to/repo, followed by an optional target directory.

> glab repo clone gitlab-org/cli
Cloning into 'cli'...
remote: Enumerating objects: 18691, done.
remote: Counting objects: 100% (72/72), done.
remote: Compressing objects: 100% (34/34), done.
remote: Total 18691 (delta 53), reused 39 (delta 37), pack-reused 18619
Receiving objects: 100% (18691/18691), 22.98 MiB | 5.97 MiB/s, done.
Resolving deltas: 100% (12391/12391), done.

If you have multiple repositories in a group to clone, you can do this using glab as well. Use the --group option (or -g) to clone all repositories in the group sequentially:

> GITLAB_HOST=gitlab.com glab repo clone -g gitlab-org
fatal: destination path 'verify-mr-123640-security-policy-project' already exists and is not an empty directory.
Cloning into 'verify-mr-123640'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
Cloning into 'without-srp'...
remote: Enumerating objects: 30, done.
remote: Counting objects: 100% (14/14), done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 30 (delta 7), reused 4 (delta 4), pack-reused 16
Receiving objects: 100% (30/30), 5.94 KiB | 5.94 MiB/s, done.
Resolving deltas: 100% (9/9), done.
Cloning into 'container-scanning-with-sbom'...

Working with Merge Requests

After checking out the repository, you can start working on issues or merge requests (MRs).

A typical code change process often looks like this: You make your code changes, commit them, and push them to GitLab. Then, you want to create a merge request. Normally, you would now switch to the GitLab website to create the MR. Thanks to glab, you don’t need to leave the command line.

Using glab mr create, you can interactively create an MR. You will be guided through the creation process, where you specify the title and description, and then you will be asked if you want to create the MR directly or view it in the web frontend before creating it.

> glab mr create
? Choose a template Open a blank merge request
? Title: New Feature
? Description <Received>
? What's next? Submit

Creating merge request for test into master in gitlab-org/cli

!351 New Feature (test)
https://gitlab.com/gitlab-org/cli/-/merge_requests/1297

You can then view it. If you want to do this in the browser, run glab mr view with the --web (or -w) parameter.

> glab mr view -w 1297

You can also view the same content directly on the command line (including comments):

> glab mr view 1297 -R gitlab-org/cli
open • opened by rndmh3ro about 1 hour ago
docs: add installation options with wakemeops !1297

  ## Description

  Add installation options with wakemeops-repository.

  Note: I'm not affiliated with WakeMeOps, just a happy user.

  ## Related Issues

  Resolves #1363

  ## How has this been tested?

  not at all.

  ## Screenshots (if appropriate):

  ### Types of changes

  [] Bug fix (non-breaking change which fixes an issue)
  [] New feature (non-breaking change which adds functionality)
  [] Breaking change (fix or feature that would cause existing functionality
  to change)
  [✓] Documentation
  [] Chore (Related to CI or Packaging to platforms)
  [] Test gap

0 upvotes • 0 downvotes • 5 comments
Labels: Community contribution, documentation, linked-issue, tw::triaged, workflow::ready for review
Assignees: rndmh3ro
Reviewers: aqualls
Pipeline Status: success (View pipeline with `glab ci view add_wakemeops_docs`)
Approvals Status:
Rule "All Members" insufficient approvals (0/1 required):

Rule "/docs/" sufficient approvals (0/0 required):
Amy Qualls aqualls -

✓ This merge request has 1 changes

View this merge request on GitLab: https://gitlab.com/gitlab-org/cli/-/merge_requests/1297

If you’re not working on the codebase yourself but are reviewing MRs from others, you can list open merge requests with glab mr list.

> glab mr list
Showing 22 open merge requests on gitlab-org/cli (Page 1)

!1297 gitlab-org/cli!1297 docs: add installation options with wakemeops (main) ← (add_wakemeops_docs)
!1296 gitlab-org/cli!1296 fix(repo view): consider current host when viewing different repositories (#1362) (main) ← (1362_repo_view)
!1295 gitlab-org/cli!1295 fix: `glab mr delete` should work properly for forks (main) ← (fix_mr_delete)

Afterwards, you can check out the MR you want to review:

> glab mr checkout 1297

If you’re satisfied with the content, you can add a note to the Merge Request and then approve it directly:

> glab mr note -R gitlab-org/cli -m "LGTM"

> glab mr approve
- Approving Merge Request !1297
✓ Approved

And of course, you can also merge the MR right away:

> glab mr merge
? What merge method would you like to use? Rebase and merge
? What's next? Submit
✓ Rebase successful
! No pipeline running on test
✓ Rebased and merged
!1297 New Feature (test)
https://gitlab.com/gitlab-org/cli/-/merge_requests/1297

At the end of the day, you can view your merged MRs by using glab mr list options to see only merged (-M) or your own (-a @me) MRs:

> glab mr list -M -a @me
Showing 4 merged merge requests on gitlab-org/cli (Page 1)

!1279 gitlab-org/cli!1279 feat(schedule): Add commands to create and delete schedules (main) ← (create_del_sched)
!1176 gitlab-org/cli!1176 feat(schedule): Add command to run schedules (main) ← (run_schedule)
!1143 gitlab-org/cli!1143 docs: remove duplicate defaults in help (main) ← (fix_help_doc)
!1112 gitlab-org/cli!1112 feat(schedule): Add command to list schedules (main) ← (sched_list)

Working with Pipelines

Code changes are tested through an automatic CICD pipeline. Naturally, glab offers the ability to work with pipelines.

To start a pipeline on the main branch, use the following command:

> glab ci run -b main
Created pipeline (id: 540823), status: created, ref: main, weburl: https://git.example.com/example/project/-/pipelines/540823

You can view the status of the pipeline like this:

> glab ci status
(failed) • 01m 11s lint test

https://git.example.com/example/project/-/pipelines/540812
SHA: 275cb8295c69db166e1b1c94936d4c4b67463701
Pipeline State: failed

? Choose an action: Exit

If a pipeline has failed, you can view the logs using glab ci trace:

> glab ci trace

Searching for latest pipeline on test...
Getting jobs for pipeline 540812...

? Select pipeline job to trace: kics-scan (1209237) - failed

Getting job trace...
Showing logs for kics-scan job #1209237
Running with gitlab-runner 14.10.1 (f761588f)
  on example-shared-docker swAou6b9
Resolving secrets
Preparing the "docker" executor

glab works excellently with Unix pipes, so you can easily grep for errors:

> glab ci trace 1209237 | grep -i failed
Queries failed to execute: 10
ERROR: Job failed: exit code 50

Linting

Speaking of errors - you can incorporate them wonderfully into the CICD configuration file, the .gitlab-ci.yml.

If you change this file, for example to add a new stage, and make a mistake, you will usually only notice it after you have pushed your changes and wonder why the pipeline does not start.

Fortunately, you can check (“lint”) the configuration with glab.

If an error has crept in, glab ci lint will detect it.

> glab ci lint
Validating...
.gitlab-ci.yml is invalid
1 (<unknown>): did not find expected key while parsing a block mapping at line 2 column 1

After correction, the linting will then report success:

> glab ci lint
Validating...
✓ CI/CD YAML is valid!

Working with Schedules

I am particularly proud of the feature to create and run Pipeline Schedules with glab, because I implemented it.

Pipeline Schedules are designed to automatically run pipelines at regular intervals.

You can create these with glab. To do this, you pass a cron expression (which defines when the pipeline should run), a description, and the branch on which the pipeline should run:

> glab schedule create --cron "0 2 * * *" --description "Run main pipeline everyday" --ref "main" --variable "foo:bar"
Created schedule

You can view the created pipeline schedule with glab schedule list:

> glab schedule list
Showing 1 schedules on example/project (Page 1)

ID Description Cron Owner Active
1038 Run main pipeline everyday * * * * * segu true

To run the pipeline schedule outside the defined rhythm, start it with glab schedule run:

> glab schedule run 1038
Started schedule with ID 1038

And if it is no longer needed, you can simply delete it:

> glab schedule delete 1038
Deleted schedule with ID 1038

glab API

Not all functions that Gitlab offers are yet usable with glab. For such cases, it is possible to communicate directly with the Gitlab API using glab api.

The command to display the pipeline schedules (glab schedule list) mentioned in the previous section can be replicated using a glab api call:

> glab api projects/:fullpath/pipeline_schedules/
[
  {
    "id": 1038,
    "description": "Run main pipeline everyday",
    "ref": "main",
    "cron": "* * * * *",
    "cron_timezone": "UTC",
    "next_run_at": "2023-06-22T08:33:00.000Z",
    "active": true,
    "created_at": "2023-06-22T08:24:02.199Z",
    "updated_at": "2023-06-22T08:24:02.199Z",
    "owner": {
      "id": 97,
      "username": "segu",
      "name": "Sebastian Gumprich",
      "state": "active",
    }
  }
]

You can also delete the pipeline schedule this way:

> glab api projects/:fullpath/pipeline_schedules/1038 -X DELETE

> glab api projects/:fullpath/pipeline_schedules/1038
glab: 404 Pipeline Schedule Not Found (HTTP 404)
{
  "message": "404 Pipeline Schedule Not Found"
}

Aliases

To avoid having to remember the sometimes more complicated API calls, glab has functionality to create aliases.

Two aliases are already set up by default, which you can display as follows:

> glab alias list
ci pipeline ci
co mr checkout

So if you want to check out a merge request, you can simply call glab co instead of glab mr checkout.

You can define your own aliases as follows:

> glab alias set schedule_list 'api projects/:fullpath/pipeline_schedules/'
- Adding alias for schedule_list: api projects/:fullpath/pipeline_schedules/
✓ Added alias.

And of course, you can delete them again:

> glab alias delete schedule_list
✓ Deleted alias schedule_list; was api projects/:fullpath/pipeline_schedules/

Set Variables from GitlabCI Locally

Another useful glab feature is working with CICD variables.

You can display, create, and delete these as well:

> glab variable list

> glab variable set foo bar
✓ Created variable foo for 7001-07/nrwsp with scope *

> glab variable get foo
bar

> glab variable delete foo
✓ Deleted variable foo with scope * for 7001-07/nrwsp

The variables created this way can be used locally in a simple manner.

If you use Terraform, for example, you can set your TF_VAR variables easily by setting the output of glab variable get as an environment variable.

export TF_VAR_db_root_password=$(glab variable get TF_VAR_db_root_password)
export TF_VAR_secret_key=$(glab variable get TF_VAR_secret_key)
export TF_VAR_access_key=$(glab variable get TF_VAR_access_key)

If you copy these exports into your README, each team member can set the correct Terraform variables with a simple copy-paste, without having to copy them from a password manager in a cumbersome way.

Bash-Completion and Further Information

If you want to know what else glab can do - the bash autocompletion shows it to you:

And many more details can of course be found on the Homepage of glab.