GitLab is one of the leading source control and CI/CD solutions for modern software delivery teams. It provides a comprehensive set of features for planning, building, and delivering your software projects.
GitLab’s normally interacted with using its web UI or API. Neither of these options are particularly appealing to terminal-centric developers. Fortunately GitLab also has a CLI that provides direct access to your issues, merge requests, pipelines, and other resources, right alongside your code and other shell commands. This article will show you the basics.
What Is Glab?
The glab GitLab CLI was begun by Clement Sam as a community-led project. It has since been adopted by GitLab, receiving its first GitLab-led official release in December 2022. Going forwards, it’ll continue to be maintained by GitLab and the broader community as an open-source tool.
Glab currently supports interactions with the following GitLab features:
- Issues
- Merge Requests
- Pipelines
- Releases
- Repositories
- Labels
- Snippets
You can retrieve existing data from your GitLab account, create new items, and perform actions such as checking a pipeline’s status and approving a merge request. It’s possible to authenticate to multiple GitLab instances simultaneously, including GitLab.com and your self-hosted servers.
Getting Started With Glab
Before starting to use Glab, create a personal access token for your GitLab account that includes the api and write_repository scopes. Glab will use this token to perform actions on your behalf.
Click your profile icon in the top-right of the GitLab UI, then choose “Access Tokens” from the menu on the left. Give your token a name and select the api and write_repository scopes from the list. Scroll down the page and click the “Create personal access token” button. The token’s value will be displayed – note this down now, as you won’t be able to retrieve it in the future.
Next, you need to install Glab. You can download pre-built binaries for Windows, macOS, and Linux systems from the project’s GitLab Releases page. Glab’s also distributed for several popular package managers across all supported operating systems.
Once Glab’s installed, you can authenticate to your GitLab instance by running the auth login command. This will start a series of interactive prompts that let you choose between GitLab.com or a self-hosted instance. After supplying the instance details, you’ll be able to enter the personal access token you created earlier.
Next you’ll be asked to confirm the default protocol to use for Git operations. You can usually accept the value that’s automatically selected. SSH is preferred but some environments may require Git over HTTPS. The following prompt asks you whether Glab should authenticate Git operations using the same personal access token you’ve previously supplied. This is usually the desired behavior.
Finally, if you’re using a self-hosted GitLab instance, you’ll be prompted to choose between the HTTP and HTTPS protocols for access to the GitLab API. Choose HTTPS unless you know your instance only supports HTTP.
At the end of the sequence, you should receive a “Logged in” success message.
Logging Into Another GitLab Instance
You can login to another GitLab instance by repeating the auth login command. Running auth status will emit a list of all the endpoints you’ve configured.
Using Glab
Glab’s intended to be run from your project’s working directory. Begin by cd-ing into a directory that contains a Git repository. Glab commands will now automatically select the correct GitLab instance and authentication token, based on the project’s default Git remote.
This model permits seamless use of projects from multiple GitLab instances. You can run git and glab commands as you work, simply by entering a project directory. It’s possible to use Glab outside a project, however, by setting the GITLAB_TOKEN and GITLAB_URI (or GITLAB_HOST) environment variables in your shell, then specifying the --repo flag with your commands to identify the target project (in OWNER/REPO format). This lets you conveniently use Glab within automated scripts, for example.
Issues
List issues in your project with the issues list command:
$ glab issues list Showing 3 open issues in ilmiont/ardeidae that match your search (Page 1) #376 ilmiont/ardeidae#376 Console Input allow accessing full standard input string about 1 month ago #374 ilmiont/ardeidae#374 Basis support construction via compound typehints about 11 months ago #373 ilmiont/ardeidae#373 v3.1.0 unit tests about 11 months ago
Use the --page flag to switch to subsequent pages in the result set. 20 items are displayed per page by default; this can be changed with the --per-page flag.
Several filtering flags are supported. The following command fetches all closed issues with the P1 label, that are in the v3.1.0 milestone and assigned to you:
$ glab issue list --mine --milestone v3.1.0 --label P1 --closed
Run glab issue list --help to learn about all the supported flags.
Get detailed information about a specific issue with issue view:
$ glab issues view 376 open • opened by ilmiont about 1 month ago Console Input allow accessing full standard input string #376 php://input 0 upvotes • 0 downvotes • 0 comments Milestone: v3.1.0
To fetch an issue’s comments, add the --comments flag to the command. The comments will be paginated, like the issue list command.
You can open the web UI page for an issue in your default browser:
$ glab issue view 376 --web
Notes (comments) can be created against issues with the note command. The -m flag specifies the Markdown text for the note:
$ glab issue note 376 -m "This is no longer relevant"
Close and reopen issues with the close and reopen commands respectively:
$ glab issue close 376 $ glab issue reopen 376
To create a new issue, run the create command and pass appropriate flags:
$ glab issue create
--title "New Issue"
--description "Demo issue"
--milestone "v3.1.0"
You’ll be prompted to confirm the issue’s creation. You can skip this by setting the -y or --yes flag. Many more flags are supported to define all the properties of the issue. Try running glab issue create --help to explore the options.
Merge Requests
Basic merge request interactions are similar to those for issues. Use the list and view commands to retrieve details of existing merge requests. The approve, close, and merge commands apply those respective actions to the MR:
$ glab mr merge 100
Merge request commands accept either an ID or a source branch as their argument. You can merge the MR for demo-branch into your main branch using the following command:
$ glab mr merge demo-branch
You can view the changes contained in an MR with the diff command:
$ glab mr diff 100
Colorized diff output will be displayed in your terminal in Git format.
It’s also possible to locally checkout and switch to a merge request’s source branch, without manually running Git commands:
$ glab mr checkout 100
CI Pipelines
View pipeline results for your project by running ci list:
$ glab ci list Showing 3 pipelines on ilmiont/ardeidae (Page 1) (success) • #734 3.1.0-rc42 (about 9 days ago) (success) • #733 master (about 9 days ago) (success) • #732 Dbal-store-allow-upsert (about 9 days ago)
The view command provides access to the job results for the latest pipeline on either the default or a specific branch. A new terminal screen will display the stages in the pipeline:
$ glab ci view $ glab ci view -b demo-branch
To trigger a new pipeline run, execute the glab run command:
$ glab ci run
You can specify the branch to source the pipeline from:
$ glab ci run -b demo-branch
It’s also possible to set CI variables for the run:
$ glab ci run --variables demo-var:demo-val,another-var:another-val
You can access a job’s logs by running the ci trace command and using the interactive prompt to select the target job. Artifacts are available too: the ci artifact command downloads the artifacts from the latest pipeline, for either the default branch or a specified one identified by the -b flag.
Finally, Glab includes a built-in linter for the .gitlab-ci.yml file in your working directory. This allows you to conveniently check your pipeline’s validity, without copying and pasting the file into the GitLab web UI.
$ glab ci lint Getting contents in .gitlab-ci.yml Validating... ✓ CI yml is Valid!
Arbitrary API Requests
Glab’s commands are wrappers around existing GitLab API endpoints. While several APIs are natively supported, many more are yet to be implemented as commands. Calling the API directly can be tedious because you need to supply your personal access token by manually setting request headers.
Glab includes a utility command for making arbitrary authenticated requests against the API. The glab api command accepts a relative URI to request in the context of your active GitLab instance. The following example gets the Git tags associated with the project with the ID of 1:
$ glab api projects/1/repository/tags
The raw API response data will be emitted to your terminal in JSON format.
Set the HTTP method for the request using the -X or --method flag. You can supply request body data with the -F or --field flag:
$ glab api projects/1/repository/tags -X POST --field tag_name=demo --field ref=main
You can include custom request headers by setting the -H or --header flag.
Using Aliases
Glab supports custom command aliases so you can quickly access commonly used functionality.
Create a new alias by running the alias set command:
$ glab alias set issues "issue list" - Adding alias for issues: issue list ✓ Added alias.
Now you can list the issues in your project by running glab issues:
$ glab issues Showing 3 open issues in ilmiont/ardeidae that match your search (Page 1) #376 ilmiont/ardeidae#376 Console Input allow accessing full standard input string about 1 month ago #374 ilmiont/ardeidae#374 Basis support construction via compound typehints about 11 months ago #373 ilmiont/ardeidae#373 v3.1.0 unit tests about 11 months ago
List all the aliases you’ve created with alias list:
$ glab alias list ci pipeline ci co mr checkout issues issue list
Delete an alias by running alias delete and passing its name:
$ glab alias delete issues
Using Glab to Manage DevOps
Glab is the official GitLab CLI. It lets you manage the entire DevOps process from your terminal. You can create issues, assign tasks, review merge requests, trigger CI pipelines, and tag releases, without having to switch between tools or learn the GitLab API. This reduces context switching and facilitates automation of your most common workflows.
Having access to GitLab data alongside your code and Git operations keeps you focused on the task at hand. The CLI is also quicker to use than the web UI, if you’re comfortable with working in a terminal. It’s a valuable third interface for your GitLab instance, in addition to the UI and API.
While this article has covered the basics of using Glab for common tasks, there’s much more you can explore too. Check out the documentation or try running glab help and glab <COMMAND> --help to explore all the available capabilities.
Now that Glab is fully incorporated as a native GitLab project, further development is promised to support additional workflows and implement community requests. You can provide your feedback to GitLab by opening an issue in the project’s repository.
