A GitLab CLI tool bringing GitLab to your command line
Go to file
Oscar Tovar 969fbfa267 Merge branch 'glab_ci_show' into 'main'
feat(ci): add command to show full gitlab-ci configuration

Closes #7409

See merge request https://gitlab.com/gitlab-org/cli/-/merge_requests/1388

Merged-by: Oscar Tovar <otovar@gitlab.com>
Approved-by: Amy Qualls <aqualls@gitlab.com>
Approved-by: Oscar Tovar <otovar@gitlab.com>
Reviewed-by: Gary Holtz <gholtz@gitlab.com>
Reviewed-by: Sebastian Gumprich <gitlab@gumpri.ch>
Reviewed-by: Oscar Tovar <otovar@gitlab.com>
Co-authored-by: Sebastian Gumprich <sebastian.gumprich@telekom.de>
Co-authored-by: Sebastian Gumprich <gitlab@gumpri.ch>
Co-authored-by: Amy Qualls <aqualls@gitlab.com>
2024-02-13 15:05:10 +00:00
.gitlab docs: Create minimal template for docs MRs 2023-11-29 20:17:15 +00:00
api feat(schedule): add option to create a scheduled pipeline with variables 2024-01-02 20:31:50 +00:00
cmd chore: update Vale and Markdownlint versions and configuration 2023-11-20 16:15:41 +10:00
commands feat(ci): add compile command to show full ci config 2024-02-13 15:05:10 +00:00
docs feat(ci): add compile command to show full ci config 2024-02-13 15:05:10 +00:00
internal chore(dependency): update to github.com/google/renameio/v2 2024-01-09 15:52:48 +00:00
pkg fix(mr create): support non-english languages 2023-10-30 16:20:43 +10:00
scripts chore: remove script for install method 2023-01-25 13:52:09 -06:00
snap chore: Updating snapcraft info 2023-05-17 12:13:58 -05:00
test fix: remove executable flag from non-executables 2023-04-27 01:56:44 +00:00
.gitignore chore(ci): save test log as an artifact 2023-07-11 16:20:39 +10:00
.gitlab-ci.yml chore: Vale and Markdown rule refresh for project 2024-02-09 11:29:30 +10:00
.gitpod.yml [Suggestion] - 🚀 Init gitpod configuration file 2022-10-17 17:53:10 +00:00
.golangci.yml chore: re-add linting/formatting job to ci 2022-11-17 18:36:09 +00:00
.goreleaser.yml fix: goreleaser deprecated replacements, fixing the filename templates 2023-06-29 21:44:45 -05:00
.markdownlint-cli2.yaml chore: Vale and Markdown rule refresh for project 2024-02-09 11:29:30 +10:00
.projections.json.example Adding a very simple projectionist config 2022-09-12 10:26:51 -05:00
.tool-versions chore: Vale and Markdown rule refresh for project 2024-02-09 11:29:30 +10:00
.vale.ini docs: add linting and checks to documentation 2022-10-21 14:38:48 +00:00
CODE_OF_CONDUCT.md chore: fix broken link 2023-04-20 09:44:53 +00:00
CONTRIBUTING.md build: upgrade go version from 1.19 to 1.21 2024-01-08 16:27:49 +01:00
Dangerfile ci: add review roulette danger plugin 2022-11-23 12:37:15 +01:00
Dockerfile build/goreleaser: docker images 2021-06-08 02:55:18 +00:00
LICENSE chore: modify MIT license and inspiration 2023-04-07 02:09:26 +00:00
Makefile chore: Do not set CGO_ENABLED when running tests 2023-11-08 13:07:54 +08:00
README.md docs: Add mention of 1Password collaboration 2024-02-08 21:13:25 +00:00
SECURITY.md chore: Update which docs files are linted 2023-09-18 18:42:54 +00:00
gl-code-quality-report.json feat(schedule): Add command to list schedules 2023-01-02 07:55:17 +00:00
go.mod Merge branch 'dcouture-upgrade-go-1-20' into 'main' 2024-01-10 07:38:23 +00:00
go.sum Merge branch 'dcouture-upgrade-go-1-20' into 'main' 2024-01-10 07:38:23 +00:00

README.md

GLab

GLab

GLab is an open source GitLab CLI tool bringing GitLab to your terminal next to where you are already working with git and your code without switching between windows and browser tabs. Work with issues, merge requests, watch running pipelines directly from your CLI among other features.

glab is available for repositories hosted on GitLab.com and self-managed GitLab instances. glab supports multiple authenticated GitLab instances and automatically detects the authenticated hostname from the remotes available in the working Git directory.

command example

Table of contents

Requirements

glab officially supports GitLab versions 16.0 and later. Certain commands might require more recent versions. While many commands might work properly in GitLab versions 15.x and earlier, no support is provided for these versions.

Usage

To get started with glab:

  1. Follow the installation instructions appropriate for your operating system.
  2. Authenticate into your instance of GitLab.
  3. Optional. Configure glab further to meet your needs:

You're ready!

Core commands

Run glab --help to view a list of core commands in your terminal.

Commands follow this pattern:

glab <command> <subcommand> [flags]

Many core commands also have sub-commands. Some examples:

  • List merge requests assigned to you: glab mr list --assignee=@me
  • List review requests for you: glab mr list --reviewer=@me
  • Approve a merge request: glab mr approve 235
  • Create an issue, and add milestone, title, and label: glab issue create -m release-2.0.0 -t "My title here" --label important

GitLab Duo commands

The GitLab CLI also provides support for GitLab Duo AI/ML powered features. These include:

Use glab ask to ask questions about git commands. It can help you remember a command you forgot, or provide suggestions on how to run commands to perform other tasks.

Demo

asciicast

Documentation

Read the documentation for usage instructions or check out glab help.

Installation

Download a binary suitable for your OS at the releases page. Other installation methods depend on your operating system.

Homebrew

Homebrew is the officially supported package manager for macOS, Linux, and Windows (through Windows Subsystem for Linux)

  • Homebrew
    • Install with: brew install glab
    • Update with: brew upgrade glab

Other installation methods

Other options to install the GitLab CLI that may not be officially support or are maintained by the community are also available.

Building from source

If a supported binary for your OS is not found at the releases page, you can build from source:

Prerequisites for building from source

  • make
  • Go 1.21+

To build from source:

  1. Run the command go version to verify that Go version 1.21 or later is installed. If go is not installed, follow instructions on the Go website.
  2. Run the go install gitlab.com/gitlab-org/cli/cmd/glab@main to install glab cmd in $GOPATH/bin.
  3. The sources of glab will be in $GOPATH/src/gitlab.com/gitlab-org/cli.
  4. If you do not have $GOPATH/bin or $GOBIN in your $PATH, run export PATH=$PWD/bin:$PATH to update your PATH with the newly compiled project.
  5. Run glab version to confirm that it worked.

Authentication

OAuth (GitLab.com only)

To authenticate your installation of glab with OAuth:

  1. Start interactive setup with glab auth login.
  2. For the GitLab instance you want to sign in to, select GitLab.com.
  3. For the login method, select Web. This selection launches your web browser to request authorization for the GitLab CLI to use your GitLab.com account.
  4. Select Authorize.
  5. Complete the authentication process in your terminal, selecting the appropriate options for your needs.

Personal Access Token

To authenticate your installation of glab with a personal access token:

  1. Get a GitLab personal access token with at least the api and write_repository scopes. Use the method appropriate for your instance:
    • For GitLab.com, create one at the Personal access tokens page.
    • For self-managed instances, visit https://gitlab.example.com/-/profile/personal_access_tokens?scopes=api,write_repository, modifying gitlab.example.com to match the domain name of your instance.
  2. Start interactive setup: glab auth login
  3. Authenticate with the method appropriate for your GitLab instance:
    • For GitLab SaaS, authenticate against gitlab.com by reading the token from a file: glab auth login --stdin < myaccesstoken.txt
    • For self-managed instances, authenticate by reading from a file: glab auth login --hostname gitlab.example.com --stdin < myaccesstoken.txt. This will allow you to perform authenticated glab commands against a self-managed instance when you are in a Git repository with a remote matching your self-managed instance's host. Alternatively set GITLAB_HOST to direct your command to your self-managed instance.
    • Authenticate with token and hostname: glab auth login --hostname gitlab.example.org --token xxxxx Not recommended for shared environments.

Configuration

By default, glab follows the XDG Base Directory Spec. Configure it globally, locally, or per host:

  • Globally: run glab config set --global editor vim.
    • The global configuration file is available at ~/.config/glab-cli/config.yml.
    • To override this location, set the GLAB_CONFIG_DIR environment variable.
  • The current repository: run glab config set editor vim in any folder in a Git repository.
    • The local configuration file is available at .git/glab-cli/config.yml in the current working Git directory.
  • Per host: run glab config set editor vim --host gitlab.example.org, changing the --host parameter to meet your needs.
    • Per-host configuration info is always stored in the global configuration file, with or without the global flag.

Configure glab to use your self-managed instance

When outside a Git repository, glab uses gitlab.com by default. For glab to default to your self-managed instance when you are not in a Git repository, change the host configuration settings. Use this command, changing gitlab.example.com to the domain name of your instance:

glab config set -g host gitlab.example.com

Setting this configuration enables you to perform commands outside a Git repository while using your self-managed instance. For example:

  • glab repo clone group/project
  • glab issue list -R group/project

If you don't set a default domain name, you can declare one for the current command with the GITLAB_HOST environment variable, like this:

  • GITLAB_HOST=gitlab.example.com glab repo clone group/project
  • GITLAB_HOST=gitlab.example.com glab issue list -R group/project

When inside a Git repository glab will use that repository's GitLab host by default. For example glab issue list will list all issues of the current directory's Git repository.

Configure glab to use self-signed certificates for self-managed instances

The GitLab CLI can be configured to support self-managed instances using self-signed certificate authorities by making either of the following changes:

You can disable TLS verification with:

glab config set skip_tls_verify true --host gitlab.example.com

Or add the path to the self signed CA:

glab config set ca_cert /path/to/server.pem --host gitlab.example.com

Environment variables

  • GITLAB_TOKEN: an authentication token for API requests. Setting this avoids being prompted to authenticate and overrides any previously stored credentials. Can be set in the config with glab config set token xxxxxx
  • GITLAB_URI or GITLAB_HOST: specify the URL of the GitLab server if self-managed (eg: https://gitlab.example.com). Default is https://gitlab.com.
  • GITLAB_API_HOST: specify the host where the API endpoint is found. Useful when there are separate (sub)domains or hosts for Git and the API endpoint: defaults to the hostname found in the Git URL
  • GITLAB_REPO: Default GitLab repository used for commands accepting the --repo option. Only used if no --repo option is given.
  • GITLAB_GROUP: Default GitLab group used for listing merge requests, issues and variables. Only used if no --group option is given.
  • REMOTE_ALIAS or GIT_REMOTE_URL_VAR: git remote variable or alias that contains the GitLab URL.
  • GLAB_CONFIG_DIR: Directory where glab's global configuration file is located. Defaults to ~/.config/glab-cli/ if not set. Can be set in the config with glab config set remote_alias origin
  • VISUAL, EDITOR (in order of precedence): the editor tool to use for authoring text. Can be set in the config with glab config set editor vim
  • BROWSER: the web browser to use for opening links. Can be set in the configuration with glab config set browser mybrowser
  • GLAMOUR_STYLE: environment variable to set your desired Markdown renderer style Available options are (dark|light|notty) or set a custom style
  • NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output.
  • FORCE_HYPERLINKS: set to 1 to force hyperlinks to be output, even when not outputting to a TTY

Token and environment variable precedence

GLab uses tokens in this order:

  1. Environment variable (GITLAB_TOKEN).
  2. Configuration file ($HOME/.config/glab-cli/config.yml).

Issues

If you have an issue: report it on the issue tracker

Contributing

Feel like contributing? That's awesome! We have a contributing guide and Code of conduct to help guide you.

Versioning

This project follows the SemVer specification.

Classify version changes

  • If deleting a command, changing how it behaves, or adding a new required flag, the release must use a new MAJOR revision.
  • If adding a new command or optional flag, the release must use a new MINOR revision.
  • If fixing a bug, the release must use a new PATCH revision.

Compatibility

We do our best to introduce breaking changes only when releasing a new MAJOR version. Unfortunately, there are situations where this is not possible, and we may introduce a breaking change in a MINOR or PATCH version. Some of situations where we may do so:

  • If a security issue is discovered, and the solution requires a breaking change, we may introduce such a change to resolve the issue and protect our users.
  • If a feature was not working as intended, and the bug fix requires a breaking change, the bug fix may be introduced to ensure the functionality works as intended.
  • When feature behavior is overwhelmingly confusing due to a vague specification on how it should work. In such cases, we may refine the specification to remove the ambiguity, and introduce a breaking change that aligns with the refined specification. For an example of this, see merge request 1382.
  • Experimental features are not guaranteed to be stable, and can be modified or removed without a breaking change.

Breaking changes are a last resort, and we try our best to only introduce them when absolutely necessary.

Inspiration

The GitLab CLI was adopted from Clement Sam in 2022 to serve as the official CLI of GitLab. Over the years the project has been inspired by both the GitHub CLI and Zaq? Wiedmann's lab.

Lab has served as the foundation for many of the GitLab CI/CD commands including ci view and ci trace.