Quick Links
GitLabis one of the leading source control and CI/CD solutions for modern software delivery teams. It provides a comprehensive set of features forplanning,building, anddeliveringyour 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 hasa CLIthat 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
GitLab CLI was begunby Clement Samas a community-led project. It has since been adopted by GitLab,receiving its first GitLab-led official releasein 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:
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 apersonal access tokenfor your GitLab account that includes the
and
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
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’re able to download pre-built binaries for Windows, macOS, and Linux systems from the project’sGitLab Releases page. Glab’s also distributed forseveral popular package managersacross all supported operating systems.
Once Glab’s installed, you may authenticate to your GitLab instance by running the
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.
You can login to another GitLab instance by repeating the
command. Running
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
-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
commands as you work, simply by entering a project directory. It’s possible to use Glab outside a project, however, by setting the
(or
)environment variablesin your shell, then specifying the
flag with your commands to identify the target project (in
format). This lets you conveniently use Glab within automated scripts, for example.
List issues in your project with the
command:
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–pageflag to switch to subsequent pages in the result set. 20 items are displayed per page by default; this can be changed with the–per-pageflag.
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:
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–commentsflag to the command. The comments will be paginated, like theissue listcommand.
You can open the web UI page for an issue in your default browser:
Notes (comments) can be created against issues with thenotecommand. The-mflag specifies the Markdown text for the note:
Close and reopen issues with thecloseandreopencommands respectively:
$ glab issue reopen 376
To create a new issue, run thecreatecommand and pass appropriate flags:
–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-yor–yesflag. Many more flags are supported to define all the properties of the issue. Try runningglab issue create –helpto explore the options.
Merge Requests
Basic merge request interactions are similar to those for issues. Use thelistandviewcommands to retrieve details of existing merge requests. Theapprove,close, andmergecommands 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 fordemo-branchinto your main branch using the following command:
you may view the changes contained in an MR with thediffcommand:
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:
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)
Theviewcommand 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 -b demo-branch
It’s also possible to setCI variablesfor the run:
You can access a job’s logs by running theci tracecommand and using the interactive prompt to select the target job. Artifacts are available too: theci artifactcommand downloads the artifacts from the latest pipeline, for either the default branch or a specified one identified by the-bflag.
Finally, Glab includes a built-in linter for the.gitlab-ci.ymlfile 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.
Getting contents in .gitlab-ci.yml
✓ CI yml is Valid!
Arbitrary API Requests
Glab’s commands are wrappers around existingGitLab APIendpoints. 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. Theglab apicommand 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 of1:
The raw API response data will be emitted to your terminal in JSON format.
Set the HTTP method for the request using the-Xor–methodflag. You can supply request body data with the-For–fieldflag:
You can include custom request headers by setting the-Hor–headerflag.
Using Aliases
Glab supports custom command aliases so you can quickly access commonly used functionality.
- Adding alias for issues: issue list
✓ Added alias.
Now you can list the issues in your project by runningglab issues:
ci pipeline ci
co mr checkout
issues issue list
Using Glab to Manage DevOps
Glab is the official GitLab CLI. It lets you manage the entire DevOps process from your terminal. you’re able to 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 outthe documentationor try runningglab helpandglab –helpto explore all the available capabilities.
Now that Glab isfully incorporatedas 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 inthe project’s repository.
