Gitlab von der Kommandozeile aus bedienen

Glab ist ein Opensource-Tool, das es ermöglicht mit Gitlab über die Kommandozeile zu arbeiten. Dadurch entfällt das Wechseln zum Browser, um Merge Requests zu erstellen oder zu genehmigen, einen Pipeline-Lauf zu starten oder Issues anzusehen.

Glab kann mit Repositories arbeiten, die auf gitlab.com gehostet sind, aber auch mit eigenen Gitlab-Instanzen. Das Tool erkennt automatisch, mit welcher Instanz es gerade arbeiten soll.

Das CLI-Tool wurde von Clement Sam gestartet und ist seit 2022 ein offizielles Gitlab-Produkt.

Setup

Glab kann auf verschiedene Arten installiert werden. Da es in Golang geschrieben ist, kann die ausführbare Datei problemlos über die Releases-Seite heruntergeladen und ausgeführt werden. Alternativ ist Glab auch in verschiedenen Paket-Repositories verfügbar. Es läuft unter Linux, Windows und macOS.

Alle Installationsvarianten kann man hier finden!

Registrierung an der GitLab-Instanz

Bevor man mit Repositories arbeiten kann, muss man sich an der Gitlab-Instanz authentifizieren. Hierfür benötigt man ein Personal Access Token, welches man sich in seinem Gitlab-Profil erstellen kann. Im Falle der gitlab.com-Instanz ist die Erstellung hier zu finden. Man vergibt einen beliebigen Namen für das Token und wählt die Berechtigungen “api” und “write_repository”. Das generierte Token wird dann im nächsten Schritt benötigt.

Nun meldet man sich mit dem Token an der Gitlab-Instanz an, indem man glab auth login ausführt und die gestellten Fragen beantwortet.

> glab auth login
? What GitLab instance do you want to log into? 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
The minimum required scopes are 'api' and 'write_repository'.
? Paste your authentication token: **************************? Choose default git protocol HTTPS
? Authenticate Git with your GitLab credentials? Yes
- glab config set -h gitlab.com git_protocol https
✓ Configured git protocol
- glab config set -h gitlab.com api_protocol https
✓ Configured API protocol
✓ Logged in as rndmh3ro

Den erfolgreichen Login kann man mittels glab auth status überprüfen.

> glab auth status
gitlab.com
  ✓ Logged in to gitlab.com as rndmh3ro (/home/segu/.config/glab-cli/config.yml)
  ✓ Git operations for gitlab.com configured to use https 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: **************************
git.example.com
  ✓ Logged in to git.example.com as segu (/home/segu/.config/glab-cli/config.yml)
  ✓ Git operations for git.example.com configured to use https protocol.
  ✓ API calls for git.example.com are made over https protocol
  ✓ REST API Endpoint: https://git.example.com/api/v4/
  ✓ GraphQL Endpoint: https://git.example.com/api/graphql/
  ✓ Token: **************************

Mit Repositories arbeiten

Hat man sich erfolgreich an der GitLab-Instanz angemeldet, kann man mittels glab mit Repositories arbeiten.

Repository klonen

Zu erst einmal will man natürlich Repositories mittels glab clonen. Dazu ruft man glab repo clone path/to/repo auf, gefolgt von einem optionalen Zielverzeichnis.

> glab repo clone gitlab-org/cli
Cloning into 'cli'...
remote: Enumerating objects: 18691, done.
remote: Counting objects: 100% (72/72), done.
remote: Compressing objects: 100% (34/34), done.
remote: Total 18691 (delta 53), reused 39 (delta 37), pack-reused 18619
Receiving objects: 100% (18691/18691), 22.98 MiB | 5.97 MiB/s, done.
Resolving deltas: 100% (12391/12391), done.

Hat man mehrere Repositories in einer Gruppe, die man clonen möchte, kann man dies mittels glab ebenfalls tun. Hierzu muss man die --group-Option (oder -g) nutzen. Damit werden nacheinander alle Repositories der Gruppe gecloned:

> GITLAB_HOST=gitlab.com glab repo clone -g gitlab-org
fatal: destination path 'verify-mr-123640-security-policy-project' already exists and is not an empty directory.
Cloning into 'verify-mr-123640'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
Cloning into 'without-srp'...
remote: Enumerating objects: 30, done.
remote: Counting objects: 100% (14/14), done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 30 (delta 7), reused 4 (delta 4), pack-reused 16
Receiving objects: 100% (30/30), 5.94 KiB | 5.94 MiB/s, done.
Resolving deltas: 100% (9/9), done.
Cloning into 'container-scanning-with-sbom'...

Mit Merge Requests arbeiten

Nachdem das Repository ausgecheckt wurde, kann man mit der Arbeit an Issues oder Merge Requests (MRs) beginnen.

Ein normaler Prozess zur Codeänderung sieht meist so aus: Man führt seine Codeänderungen durch, committed sie und pushed sie anschließend in das Gitlab. Daraufhin möchte man einen Merge Request erstellen. Normalerweise würde man nun zur Gitlab-Website wechseln und dort den MR erstellen. Dank glab muss man die Kommandozeile aber nicht verlassen.

Mittels glab mr create wird interaktiv ein MR erstellt. Dabei wird man durch den Erstellungsprozess geführt, indem man Titel und Beschreibung angibt und anschließend gefragt wird, ob man den MR direkt erstellen will oder ihn sich im Webfrontend ansehen will, bevor er erstellt wird.

> glab mr create
? Choose a template Open a blank merge request
? Title: New Feature
? Description <Received>
? What's next? Submit

Creating merge request for test into master in gitlab-org/cli

!351 New Feature (test)
https://gitlab.com/gitlab-org/cli/-/merge_requests/1297

Danach kann man ihn sich ansehen. Möchte man das im Browser tun, ruft man glab mr view mit dem Parameter --web (oder -w) auf.

> glab mr view -w 1297

Man kann sich die gleichen Inhalte aber auch direkt auf der Kommandozeile ansehen (inklusive Kommentare):

> glab mr view 1297 -R gitlab-org/cli
open • opened by rndmh3ro about 1 hour ago
docs: add installation options with wakemeops !1297

  ## Description

  Add installation options with wakemeops-repository.

  Note: I'm not affiliated with WakeMeOps, just a happy user.

  ## Related Issues

  Resolves #1363

  ## How has this been tested?

  not at all.

  ## Screenshots (if appropriate):

  ### Types of changes

  [] Bug fix (non-breaking change which fixes an issue)
  [] New feature (non-breaking change which adds functionality)
  [] Breaking change (fix or feature that would cause existing functionality
  to change)
  [✓] Documentation
  [] Chore (Related to CI or Packaging to platforms)
  [] Test gap

0 upvotes • 0 downvotes • 5 comments
Labels: Community contribution, documentation, linked-issue, tw::triaged, workflow::ready for review
Assignees: rndmh3ro
Reviewers: aqualls
Pipeline Status: success (View pipeline with `glab ci view add_wakemeops_docs`)
Approvals Status:
Rule "All Members" insufficient approvals (0/1 required):

Rule "/docs/" sufficient approvals (0/0 required):
Amy Qualls aqualls -

✓ This merge request has 1 changes

View this merge request on GitLab: https://gitlab.com/gitlab-org/cli/-/merge_requests/1297

Arbeitet man gerade nicht selbst an der Codebasis sondern sieht sich MRs anderer Personen an, kann man sich mittels glab mr list offene Merge-Requests anzeigen lassen.

> glab mr list
Showing 22 open merge requests on gitlab-org/cli (Page 1)

!1297 gitlab-org/cli!1297 docs: add installation options with wakemeops (main) ← (add_wakemeops_docs)
!1296 gitlab-org/cli!1296 fix(repo view): consider current host when viewing a repo details (main) ← (jmc-1334)
!1295 gitlab-org/cli!1295 chore(ci): remove ssh key from build (main) ← (jmc-remove-ssh)

Im Anschluss checkt man den MR aus, den man sich ansehen möchte:

> glab mr checkout 1297

Ist man mit dem Inhalt zufrieden, kann man dem Merge Request zum Beispiel eine Notiz hinzufügen und anschließend direkt approven:

> glab mr note -R gitlab-org/cli -m "LGTM"

> glab mr approve
- Approving Merge Request !1297
✓ Approved

Und natürlich kann man den MR auch gleich mergen:

> glab mr merge
? What merge method would you like to use? Rebase and merge
? What's next? Submit
✓ Rebase successful
! No pipeline running on test
✓ Rebased and merged
!1297 New Feature (test)
https://gitlab.com/gitlab-org/cli/-/merge_requests/1297

Um sich am Ende des Tages seine gemergeden MRs anzusehen, gibt man glab mr list Optionen mit, um nur gemergede (-M) oder meine eigenen (-a @me) MRs anzusehen:

> glab mr list -M -a @me
Showing 4 merged merge requests on gitlab-org/cli (Page 1)

!1279 gitlab-org/cli!1279 feat(schedule): Add commands to create and delete schedules (main) ← (create_del_sched)
!1176 gitlab-org/cli!1176 feat(schedule): Add command to run schedules (main) ← (run_schedule)
!1143 gitlab-org/cli!1143 docs: remove duplicate defaults in help (main) ← (fix_help_doc)
!1112 gitlab-org/cli!1112 feat(schedule): Add command to list schedules (main) ← (sched_list)

Mit Pipelines arbeiten

Code-Änderungen werden durch eine automatische CICD-Pipeline getestet. Natürlich bietet glab die Möglichkeit, mit Pipelines zu arbeiten.

Zum Starten einer Pipeline auf dem Main-Branch ruft man folgenden Befehl auf:

> glab ci run -b main
Created pipeline (id: 540823 ), status: created , ref: main , weburl: https://git.example.com/example/project/-/pipelines/540823 )

Den Status der Pipeline kann man sich so ansehen:

> glab ci status
(failed) • 01m 11s lint test

https://git.example.com/example/project/-/pipelines/540812
SHA: 275cb8295c69db166e1b1c94936d4c4b67463701
Pipeline State: failed

? Choose an action: Exit

Ist eine Pipeline fehlgeschlagen, kann man sich die Logs mittels glab ci trace ansehen:

> glab ci trace

Searching for latest pipeline on test...
Getting jobs for pipeline 540812...

? Select pipeline job to trace: kics-scan (1209237) - failed

Getting job trace...
Showing logs for kics-scan job #1209237
Running with gitlab-runner 14.10.1 (f761588f)
  on example-shared-docker swAou6b9
Resolving secrets
Preparing the "docker" executor

glab arbeitet hervorragend mit Unix-Pipes zusammen - so kann man sich Fehler einfach heraus greppen:

> glab ci trace 1209237 | grep -i failed
Queries failed to execute: 10
ERROR: Job failed: exit code 50

Linting

Wo wir von Fehlern sprechen - man kann sie wunderbar in der CICD-Konfigurationsdatei, der .gitlab-ci.yml einbauen.

Ändert man diese Datei, weil man zum Beispiel eine neue Stage einbauen möchte und macht dabei einen Fehler, bekommt man diesen normalerweise erst mit, wenn man seine Änderungen gepushed hat und sich wundert, warum die Pipeline nicht losläuft.

Zum Glück kann man mit glab die Konfiguration überprüfen (“linten”).

Hat sich ein Fehler eingeschlichen, wird glab ci lint diesen feststellen.

> glab ci lint
Validating...
.gitlab-ci.yml is invalid
1 (<unknown>): did not find expected key while parsing a block mapping at line 2 column 1

Nach der Korrektur meldet das Linting dann Erfolg:

> glab ci lint
Validating...
✓ CI/CD YAML is valid!

Mit Schedules arbeiten

Auf das Feature, Pipeline Schedules mittels glab zu erstellen und laufen zu lassen, bin ich ganz besonders stolz, denn ich habe sie implementiert.

Pipeline Schedules sind dafür da, Pipelines in regelmäßigen Abständen automatisch laufen zu lassen.

Man kann diese per glab anlegen lassen. Dazu übergibt man dem Befehl eine Cron-Expression (die definiert, wann die Pipeline laufen soll), eine Beschreibung sowie den Branch, auf dem die Pipeline laufen soll:

> glab schedule create --cron "0 2 * * *" --description "Run main pipeline everyday" --ref "main" --variable "foo:bar"
Created schedule

Die so angelegte Pipeline schedule kann man sich per glab schedule list ansehen:

> glab schedule list
Showing 1 schedules on example/project (Page 1)

ID Description Cron Owner Active
1038 Run main pipeline everyday * * * * * segu true

Um die Pipeline Schedule außerhalb des definierten Rythmus laufen zu lassen, startet man sie mit glab schedule run:

> glab schedule run 1038
Started schedule with ID 1038

Und wird sie nicht mehr benötigt, kann man sie einfach löschen:

> glab schedule delete 1038
Deleted schedule with ID 1038

glab API

Noch sind nicht alle Funktionen, die Gitlab bietet, auch mittels glab nutzbar. Für solche Fälle ist es möglich, mittels glab api direkt mit der Gitlab-API zu kommunizieren.

Den im vorigen Abschnitt erwähnte Befehl zum Anzeigen der Pipeline Schedules (glab schedule list) kann man mittels eines glab api-Aufrufes nachbilden:

> glab api projects/:fullpath/pipeline_schedules/
[
  {
    "id": 1038,
    "description": "Run main pipeline everyday",
    "ref": "main",
    "cron": "* * * * *",
    "cron_timezone": "UTC",
    "next_run_at": "2023-06-22T08:33:00.000Z",
    "active": true,
    "created_at": "2023-06-22T08:24:02.199Z",
    "updated_at": "2023-06-22T08:24:02.199Z",
    "owner": {
      "id": 97,
      "username": "segu",
      "name": "Sebastian Gumprich",
      "state": "active",
    }
  }
]

Auch das Löschen der Pipeline Schedule ist so möglich:

> glab api projects/:fullpath/pipeline_schedules/1038 -X DELETE

> glab api projects/:fullpath/pipeline_schedules/1038
glab: 404 Pipeline Schedule Not Found (HTTP 404)
{
  "message": "404 Pipeline Schedule Not Found"
}

Aliases

Damit man sich die teils komplizierteren API-Aufrufe nicht merken muss, existiert in glab die Funktionalität, Aliase anzulegen.

Es sind bereits zwei Aliase standardmäßig eingerichtet, die man sich wie folgt anzeigen lassen kann:

> glab alias list
ci pipeline ci
co mr checkout

Möchte man also einen Merge Request auschecken, kann man statt glab mr checkout einfach glab co aufrufen.

Eigene Aliase kann man wie folgt definieren:

> glab alias set schedule_list 'api projects/:fullpath/pipeline_schedules/'
- Adding alias for schedule_list: api projects/:fullpath/pipeline_schedules/
✓ Added alias.

Und natürlich kann man sie auch wieder löschen:

> glab alias delete schedule_list
✓ Deleted alias schedule_list; was api projects/:fullpath/pipeline_schedules/

Variablen aus der GitlabCI lokal setzen

Ein weiteres nützliches glab-Feature ist, mit CICD-Variablen zu arbeiten.

Auch diese kann man sich anzeigen lassen, sie erstellen und sie löschen:

> glab variable list

> glab variable set foo bar
✓ Created variable foo for example/project with scope *

> glab variable get foo
bar

> glab variable delete foo
✓ Deleted variable foo with scope * for example/project

Die so erstellten Variablen lassen sich auf einfache Art und Weise auch lokal nutzen.

Nutzt man beispielsweise Terraform, kann man seine TF_VAR-Variablen ganz einfach setzen, indem man die Ausgabe von glab variable get als Umgebungsvariable setzt.

export TF_VAR_db_root_password=$(glab variable get TF_VAR_db_root_password)
export TF_VAR_secret_key=$(glab variable get TF_VAR_secret_key)
export TF_VAR_access_key=$(glab variable get TF_VAR_access_key)

Kopiert man diese exports in seine README, kann jedes Teammitglieder mit einem einfachen Copy-Paste die korrekten Terraform-Variablen setzen, ohne sie umständlich aus einem Passwort-Manager zu kopieren.

Bash-Completion und weitere Infomationen

Wer nun wissen möchte, was glab noch alles kann - die bash autocompletion zeigt es einem:

Und viele weitere Informationen findet man natürlich auf der Homepage von glab.