GitLab is a popular open-source software development platform used by developers to manage their projects. It has a command line interface (CLI) that makes it easy to manage your projects from your terminal. To use GitLab’s CLI, you first need to install GitLab on your computer. Then, you can create a new project and use the following commands to start up GitLab: git init -p gitlab://localhost/myproject cd myproject git push origin master You can also use the following commands to view or change the status of your projects: git status git push origin master
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:
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:
Run glab issue list –help to learn about all the supported flags.
Get detailed information about a specific issue with issue view:
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:
Notes (comments) can be created against issues with the note command. The -m flag specifies the Markdown text for the note:
Close and reopen issues with the close and reopen commands respectively:
To create a new issue, run the create command and pass appropriate flags:
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:
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:
You can view the changes contained in an MR with the diff command:
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:
CI Pipelines
View pipeline results for your project by running ci list:
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:
To trigger a new pipeline run, execute the glab run command:
You can specify the branch to source the pipeline from:
It’s also possible to set CI variables for the run:
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.
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:
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:
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:
Now you can list the issues in your project by running glab issues:
List all the aliases you’ve created with alias list:
Delete an alias by running alias delete and passing its name:
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
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.
