GitLab CLI (glab)

glab is the official GitLab CLI: it lets you manage your projects, issues, merge requests and pipelines directly from the terminal. Instead of browsing the web interface for every operation, you script, automate and speed up your DevOps workflow. glab can also be used inside your CI/CD pipelines to automate the creation of MRs, issue tracking or the triggering of pipelines.

What you will learn

By the end of this guide, you will be able to:

Install and configure glab on Linux, macOS and Windows
Manage repositories: clone, create, list and search
Handle issues and merge requests from the terminal
Drive CI/CD pipelines: run, follow, retry
Use the GitLab API (REST and GraphQL) through glab api
Integrate glab into your pipelines to automate operations

Prerequisites

This lesson assumes that you can open a terminal, clone a repository with Git, and understand what a merge request and a pipeline are, since glab drives those objects without explaining them. It also assumes that you know what a personal access token is: the guide creates one with the api and write_repository scopes, a value you must then treat as a secret.

As for permissions, glab adds no privilege: it acts with the rights of your account on the project, exactly like the web interface. A command that would return a 403 in the browser will do the same on the command line. A Developer role is therefore enough to clone, open a merge request and follow a pipeline; anything that touches the project settings, starting with the variables under Settings > CI/CD, requires the Maintainer role. As for tools, you need glab itself, installed with one of the package managers described below (asdf, apk, Homebrew, Chocolatey), an account on gitlab.com or on a self-managed instance, and a token created from your profile. The examples are not tied to a specific version number: glab --version shows the one you installed. Upstream lessons:

First pipeline: what glab ci runs, follows and retries
Validating your pipeline: check a .gitlab-ci.yml before pushing, which is what glab ci lint does
Variables and secrets: mask and protect the GITLAB_TOKEN variable when glab runs in a job

Installing and configuring `glab`

To get the most out of glab, the first step is to install it and configure it properly on your system.

Installing `glab`

On Linux

If you are a Linux user, installing glab is easy with asdf-vm (in French):

asdf plugin add glab
asdf install glab latest
asdf set --home glab latest

On Alpine Linux

Ideal for building the GitLab CLI into your Dockerfiles (in French) and into pipeline jobs built on Alpine, whose package manager is apk:

apk add --no-cache glab

If you are not comfortable with the apk package manager, I recommend reading my guide on apk to better understand how it works.

On macOS

For macOS users, glab can be installed through Homebrew. Simply open your terminal and type:

brew install glab

On Windows

On Windows, glab can be installed with Scoop or Chocolatey. With Chocolatey, the command is:

choco install glab

The main features of the GitLab CLI

glab offers a complete set of options for managing GitLab projects efficiently. Here is a list of the main commands available in glab, each with a short description of what it does:

alias: Creates aliases for glab commands, which simplifies the use of frequent commands.
api: Gives direct access to the GitLab API, so you can make custom API requests.
auth: Used for authentication and for configuring your GitLab credentials in glab.
check-update: Checks whether a new version of glab is available.
ci: Manages CI (Continuous Integration) pipelines, including their creation, viewing and deletion.
completion: Generates autocompletion scripts for various shells, which makes typing glab commands easier.
config: Used to configure the global settings of glab.
incident: Manages incidents, in particular their creation, update and closing.
issue: Provides tools to manage issues, including creation, listing, update and closing.
label: Manages labels for issues and merge requests.
mr: Provides commands to manage merge requests, including their creation, listing, update and merge.
release: Manages releases, including their creation, listing and deletion.
repo: Provides tools to manage GitLab repositories, including creation, cloning and branch management.
schedule: Manages scheduled pipelines.
snippet: Provides commands to create and manage code snippets.
ssh-key: Manages the SSH keys associated with your GitLab account.
user: Provides tools to view and manage user information on GitLab.
variable: Manages CI/CD variables at project or group level.

Each of these commands is designed to integrate GitLab more deeply into your DevOps workflow, making the management of your projects, issues, merge requests and CI/CD more efficient and automated.

Configuring `glab`

Once glab is installed, the next step is the configuration: connecting the tool to your GitLab account with a personal access token, that is, a password dedicated to tools, created from your profile. This connection is essential for glab to interact with your GitLab projects.

The configuration commands

Authenticating with `glab auth`

The glab auth command is used to authenticate with GitLab. It lets you configure your credentials for a seamless integration with your GitLab projects.

Interactive authentication:

Type the following command, which starts the login assistant for gitlab.com, then answer the questions displayed below it:

glab auth login --hostname 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?scopes=api,write_repository
The minimum required scopes are 'api' and 'write_repository'.
? Paste your authentication token: **************************
? Choose default git protocol SSH
* glab config set -h gitlab.com git_protocol ssh
✓ Configured git protocol
* glab config set -h gitlab.com api_protocol https
✓ Configured API protocol
✓ Logged in as Bob74

The assistant asks three questions: the login method (Token), the personal access token to paste (the link in the Tip generates it, with at least the api and write_repository scopes), then the default Git protocol, SSH or HTTPS. The last ✓ Logged in as line confirms the login. Without --hostname, glab first asks which instance to use: GitLab.com or a self-managed instance.

Non-interactive authentication:

Use the GITLAB_TOKEN variable for authentication without interaction, ideal for scripts or CI/CD environments.

To check authentication and configuration, run glab auth status: the command reads the saved configuration and prints one line per check, preceded by ✓ when it succeeds. The ✓ marks are emitted by glab itself.

glab auth status

gitlab.com
  ✓ Logged in to gitlab.com as Bob74 (/home/dev/.config/glab-cli/config.yml)
  ✓ Git operations for gitlab.com configured to use ssh 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 found: **************************

If you get x gitlab.com: api call failed: GET https://gitlab.com/api/v4/user: 401 followed by x No token provided instead, glab found no token for this host, or the token is expired or revoked: the 401 error comes from GitLab, which refuses an unauthenticated call. Run glab auth login again, or export the GITLAB_TOKEN variable.

Managing global settings with `glab config`

glab config lets you customise, with set, how glab is used by configuring global settings.

Set your preferred text editor: glab config set editor vim.
Configure the browser used to open links: glab config set browser firefox.

To display a setting, use the get option. After the set browser firefox above, it returns the saved value:

glab config get browser
firefox

Managing SSH keys with `glab ssh-key`

The glab ssh-key command helps you manage the SSH keys that secure your Git operations.

Add an SSH key to GitLab: glab ssh-key add /path/to/key.pub -t "Key title".
List the SSH keys associated with your account: glab ssh-key list.
Delete a specific SSH key: glab ssh-key delete <key_id>.

Setting up autocompletion with `glab completion`

The glab completion command of the GitLab CLI generates configuration files that enable automatic completion (autocompletion) in various shells, which makes the GitLab CLI easier to use.

Bash

Integrate it into your Bash configuration by adding:

source <(glab completion bash)

to your ~/.bashrc file.

Zsh

Add this script to your Zsh configuration file (~/.zshrc):

source <(glab completion -s zsh); compdef _glab glab

Fish

Integrate it into your Fish configuration by adding:

glab completion -s fish > ~/.config/fish/completions/glab.fish

Environment variables

The use of glab can be customised through various environment variables and configuration commands.

GITLAB_TOKEN: Avoids having to authenticate on every API request.
GITLAB_URI or GITLAB_HOST: Specifies the URL of the GitLab server for self-managed instances.
- Example: https://gitlab.example.com (default https://gitlab.com).
GITLAB_API_HOST: Specifies the host where the GitLab API lives, useful when Git and the API are on separate (sub)domains.
GITLAB_REPO: Sets the default GitLab repository for commands that accept the --repo option.
GITLAB_GROUP: Sets the default GitLab group used to list merge requests, issues and variables.
REMOTE_ALIAS or GIT_REMOTE_URL_VAR: Variable or git remote alias containing the GitLab URL.
GLAB_CONFIG_DIR: Global configuration directory of glab.
- Default: ~/.config/glab-cli/.
VISUAL, EDITOR: Sets the text editor used for writing.
BROWSER: Sets the web browser used to open links.
GLAMOUR_STYLE: Custom Markdown rendering style (options: dark, light, notty).
- NO_COLOR: Disables ANSI colouring in the output.
FORCE_HYPERLINKS: Forces the display of hyperlinks, even outside a TTY.

General `glab` commands

General commands are those that are not specific to repositories. They work even when they are not run from a directory containing a GitLab project.

Is there a new version? `glab check-update`

The update command checks whether a new version of glab is available.

glab check-update
You are already using the latest version of glab

Managing repositories with `glab repo`

The glab repo command is essential for managing repositories on GitLab, with many options for efficient management.

archive: Archive a repository.
clone: Clone a GitLab repository.
contributors: Display the contributors of a repository.
create: Create a new repository.
delete: Delete a repository.
fork: Fork a repository.
list: List the available repositories.
mirror: Configure a mirror for a repository.
search: Search for repositories.
transfer: Transfer a repository to another user or group.
view: Display the details of a repository.

Command examples:

List the available repositories:

glab repo list
Showing 30 of 57 projects (Page 1 of 2)

mon-site1/docusaurus                                git@gitlab.com:mon-site1/docusaurus.git
dockerfiles6/images/container-structure-test        git@gitlab.com:dockerfiles6/images/container-st...
Bob74/aws-blog                                      git@gitlab.com:Bob74/aws-blog.git
dockerfiles6/images/demo-cosign                     git@gitlab.com:dockerfiles6/images/demo-cosign.git

Search for repositories:

glab repo search -s docker
Showing results for "docker"
nexylan/docker/docker On steroids Docker image.  0 stars 0 forks 0 issues    updated about 19 days ago
   https://gitlab.com/nexylan/docker/docker
jitesoft/dockerfiles/docker Docker image with docker and  0 stars 0 forks 0 issues    updated about 2 months ago
   docker in docker! https://www.docker.com/
   https://gitlab.com/jitesoft/dockerfiles/docker

Assorted examples:

# Create
glab repo create --group glab-cli
glab repo create my-project
# A private project in an (existing) group, with README.md initialisation
glab repo create glab-cli/my-project -d 'my description' --private --readme -t ansible,devops

# Review
glab repo view my-project
glab repo view user/repo
glab repo view group/namespace/repo

API requests with `glab api`

The glab api command lets you send requests to the GitLab API.

Standard requests

The glab api request lets you make calls to the GitLab API. You can find the API endpoints in the documentation

glab api /projects/:id/repository/branches/

[
  {
    "name": "main",
    "commit": {
      "id": "011677bac1fb93bac5cea563c0697287c6c926f8",
      "short_id": "011677ba",
      "created_at": "2023-02-05T10:41:25.000+01:00",
      "parent_ids": ["85c5234352df02cad639787560c4137ec75b5a61"],
      "title": "Initial commit",
      "message": "Initial commit\n",
      "author_name": "Robert Stéphane",
      "author_email": "dev@example.com",
      "authored_date": "2023-02-05T10:41:25.000+01:00",
      "committer_name": "Robert Stéphane",
      "committer_email": "dev@example.com",
      "committed_date": "2023-02-05T10:41:25.000+01:00",
      "trailers": {},
      "extended_trailers": {},
      "web_url": "https://gitlab.com/Bob74/ansible-gendoc/-/commit/011677bac1fb93bac5cea563c0697287c6c926f8"
    },
    "merged": false,
    "protected": true,
    "developers_can_push": false,
...

GraphQL requests

glab api supports GraphQL, a powerful query language for APIs. With the GraphQL option, you can:

Build complex, precise queries.
Get specific data in a single request.
Handle and access data in a more flexible and efficient way.

Here is how you could use glab api to run a GraphQL query:

glab api graphql -f query='
  query {
    project(fullPath: "gitlab-org/gitlab-docs") {
      name
      forksCount
      statistics {
        wikiSize
      }
      issuesEnabled
      boards {
        nodes {
          id
          name
        }
      }
    }
  }
'

This type of query allows a deep interaction with GitLab data, offering far more flexibility and power than classic REST API requests.

Project-specific commands

The commands described below only work when they are run from a directory containing a GitLab repository.

Managing labels with `glab label`

glab label is a key command for managing labels in GitLab projects, with various options for an efficient organisation of issues and merge requests.

Here is the list of the options:

create: Create a new label.
delete: Delete a label.
edit: Edit a group or project label.
get: Display a label from its identifier.
list: List all the labels of a project.

These options cover the whole lifecycle of a label (creation, viewing, editing, deletion), for a better organisation and categorisation of the work items in your GitLab projects.

Managing issues with `glab issue`

The glab issue command provides a complete set of tools to manage issues in your GitLab projects.

Here is the list of the main options:

board: View and manage issue boards.
close: Close an issue.
create: Create a new issue.
delete: Delete an issue.
list: List issues.
note: Add a note to an issue.
reopen: Reopen a closed issue.
subscribe: Subscribe to the updates of an issue.
unsubscribe: Unsubscribe from the updates of an issue.
update: Update an issue.
view: Display the details of an issue.

Examples:

glab issue list
No open issues match your search in mon-site1/docusaurus

Managing merge requests with `glab mr`

glab mr is a command for managing merge requests in GitLab, with a wide range of options for efficient management.

Here is the list of the main options:

approve: Approve a merge request.
approvers: Manage the approvers of a merge request.
checkout: Check out a merge request locally.
close: Close a merge request.
create: Create a new merge request.
delete: Delete a merge request.
diff: Display the differences in a merge request.
fork: Fork a merge request.
issues: List the issues associated with a merge request.
list: List merge requests.
merge: Merge a merge request.
note: Add a note to a merge request.
rebase: Rebase a merge request.
reopen: Reopen a closed merge request.
revoke: Revoke a merge request approval.
subscribe: Subscribe to the updates of a merge request.
todo: Add a merge request to your to-do list.
unsubscribe: Unsubscribe from the updates of a merge request.
update: Update a merge request.
view: Display the details of a merge request.

These options allow a complete management of merge requests in your GitLab projects. Each of them gives precise control, which is essential for effective collaboration and code integration.

Managing incidents with `glab incident`

glab incident offers specific commands to manage incidents in your GitLab projects efficiently.

close: Close an incident.
list: List the incidents of a project.
note: Comment on an incident in GitLab.
reopen: Reopen a resolved incident.
subscribe: Subscribe to an incident.
unsubscribe: Unsubscribe from an incident.
view: Display the title, body and other information about an incident.

These options allow complete tracking and management of incidents, which is essential for solving critical problems quickly and efficiently.

Managing releases with `glab release`

The glab release command provides a set of tools to manage releases in your GitLab projects.

create: Create a new release.
delete: Delete a release.
download: Download the assets of a release.
list: List all the releases of a project.
upload: Upload assets to a release.
view: Display the details of a release.

These commands cover the whole lifecycle of a release, from its creation to its deletion, and make the distribution and management of versions easier in your GitLab projects.

Creating snippets with `glab snippet`

The glab snippet command is a powerful tool to manage code snippets in GitLab, enabling efficient sharing of and collaboration on pieces of code or technical information.

Example:

glab snippet create sidebars.js --title "Title of the snippet"
* Creating snippet in mon-site1/docusaurus
$3634399 Title of the snippet (sidebars.js)
 https://gitlab.com/mon-site1/docusaurus/-/snippets/3634399

Listing events with `glab user events`

The glab user events command is designed to follow the activity and events associated with a GitLab user. It is particularly useful for monitoring engagement and contributions within a project or across several GitLab projects.

This command can be used to follow the recent contributions of a user, such as commits, merge requests and comments on issues.

glab user events

Pushed to branch dev at mon-site / docusaurus
"corrections"

Pipeline commands

Managing pipelines with `glab ci`

The glab ci command is essential for managing the continuous integration (CI) side of GitLab, with a wide range of optimisation and monitoring features for CI pipelines.

An important option lets you target another repository:

  -R, --repo OWNER/REPO

The main options:

artifact: Manage the artifacts of a CI job.
ci: Display recent pipelines.
delete: Delete a pipeline.
get: Get specific details about a pipeline.
lint: Validate the .gitlab-ci.yml file.
list: List pipelines.
retry: Retry a failed pipeline.
run: Run a pipeline manually.
status: Check the status of a pipeline.
trace: Follow the execution logs of a CI job.
trigger: Trigger a pipeline through an API.
view: View the details of a pipeline.

These commands allow a complete and efficient management of CI pipelines, from their creation to their monitoring, including optimisation and debugging.

Scheduling pipelines with `glab schedule`

The glab schedule command is designed to manage scheduled pipelines in GitLab, allowing efficient automation and scheduling of CI/CD tasks.

create: Schedule a new pipeline. This option lets you configure pipelines to run automatically at specified times.
delete: Delete a scheduled pipeline using its ID. This is useful to cancel pipelines that are no longer needed.
list: Get the list of scheduled pipelines. This command gives an overview of all the pipelines scheduled in a project.
run: Manually run a scheduled pipeline. This lets you trigger a specific pipeline without waiting for its next scheduled run.

These commands offer a complete management of scheduled pipelines, from their creation to their deletion, including their execution and monitoring.

Use cases for `glab`

Using glab in these contexts optimises workflows, increases efficiency and reduces development and deployment times.

Using it on the workstation

On the workstation of a developer or a system administrator, glab allows a fast and efficient interaction with GitLab.

Repository management: Cloning, creating and managing repositories directly from the terminal.
Incident and issue tracking: Quick management of incidents and issues without going through the web interface.
Custom API requests: Use of glab api for specific requests, which makes integration with other tools or scripts easier.

Using it in CI/CD pipelines

glab is particularly useful in CI/CD pipelines to automate various GitLab-related tasks.

Merge request automation: Automatic creation of merge requests following commits or changes in branches.
Issue management: Opening and updating issues based on pipeline events.
Reporting: Sending build or test reports directly from pipelines.

Each subcommand has its own options, too many to fit here: the complete reference is published in the glab documentation, maintained in the tool's repository. For the exact help of the version installed on your machine, run glab <command> --help.

Key takeaways

glab is the official GitLab CLI to manage projects, issues, MRs and pipelines from the terminal.
Authentication through glab auth login or the GITLAB_TOKEN variable for CI/CD scripts.
glab repo to clone, create, fork and search repositories.
glab issue and glab mr to manage the complete lifecycle of issues and merge requests.
glab ci to run, follow and retry pipelines without going through the web interface.
glab api gives direct access to the REST and GraphQL API for advanced operations.
Autocompletion is available for Bash, Zsh and Fish through glab completion.

Test your knowledge

Knowledge check

Check what you have learned with this interactive quiz

10 questions

5 min

70% to pass

How it works

The timer starts when you click Start
Multiple choice, true/false and short answer questions
You can move between questions
Detailed results are shown at the end

GitLab CLI (glab)

What you will learn

Prerequisites

Installing and configuring glab

Installing glab

On Linux

On Alpine Linux

On macOS

On Windows

The main features of the GitLab CLI

Configuring glab

The configuration commands

Authenticating with glab auth

Managing global settings with glab config

Managing SSH keys with glab ssh-key

Setting up autocompletion with glab completion

Bash

Zsh

Fish

Environment variables

General glab commands

Is there a new version? glab check-update

Managing repositories with glab repo

API requests with glab api

Standard requests

GraphQL requests

Project-specific commands

Managing labels with glab label

Managing issues with glab issue

Managing merge requests with glab mr

Managing incidents with glab incident

Managing releases with glab release

Creating snippets with glab snippet

Listing events with glab user events