Gitlab CentOS 7 - API (curl)

Gitlab ist ein, in der Community Edition unter einer MIT-Lizenz zur Verfügung gestelltes System, zur Verwaltung von Git-Repositorys im Browser, was den unentgeltlichen Betrieb auf einem eigenen Server ermöglicht.

Nachfolgend soll beschrieben werden, wie ein Zugriff auf die GitLab API mittels einer *NIX - shell (hier bash) unter Nutzung des Befehls curl durchgeführt werden kann. (Inklusive Authentifizierung gegen einen bestehenden .htaccess-Schutz)

Gitlab gibt es ebenfalls in einer kostenpflichtigen Enterprise Edition

Ab hier werden root-Rechte zur Ausführung der nachfolgenden Befehle benötigt. Um der Benutzer root zu werden, geben Sie bitte nachfolgenden Befehl ein:

$ su -
Password: 

Als Voraussetzung für die hier, nachfolgend dargestellte Installation von Gitlab sind folgende Komponenten erforderlich:

• Lauffähiger Gitlab-Server z.B. Gitlab
  • Siehe auch den internen Link: GitLab CentOS 7

Nachfolgende rpm-Pakete sind als Abhängigkeit erforderlich und werden ebenfalls benötigt:

• curl - ist im base-Repository von CentOS enthalten und normalerweise bereits installiert

Um Zugriff auf die GitLab API mittels einer *NIX - shell (hier bash) unter Nutzung des Befehls curl zu erlangen sin zusätzlich zu den genannten Voraussetzungen auch die

• Erstellung eines Access Tokens

durch den Benutzer in dessen User Settings | Access Tokens (Benutzereinstellungen | Zugriff „Token“) erforderlich.

Nachfolgende Beschreibung zeigt, wie ein Access Token über die Gitlab-Web-Oberfläche erstellt werden kann.

Nach erfolgreicher Anmeldung, muss im oberen Menü das Symbol für den Benutzer ausgewählt werden und dort der Menüpunkt [Settings] (Einstellungen) ebenfalls ausgewählt werden, wie nachfolgende Bildschirmkopie zeigt:

Anschließend wird im linken Bildschirmbereich der Menüpunkt [Access Tokens] ausgewählt, wie nachfolgende Bildschirmkopie zeigt:

Hier muss nun ein Name für den Access Token vergeben werden und der Zugriff auf die api erlaubt werden, bevor die Schaltfläche [Create personal access token] ausgewählt wird, wie ebenfalls nachfolgende Bildschirmkopie zeigt:

Nachdem der Access Token erfolgreich erstellt wurde, kann dieser in die Zwischenablage des Betriebssystems kopiert werden, wie nachfolgende Bildschirmkopie zeigt:

WICHTIG - Bitte den Access Token sicher speichern, da dieser NICHT mehr in der Gitlab-Web-Oberfläche ersichtlich ist !!!

HINWEIS - Falls der Access Token vergessen wurde, kann der „vergessene“ gelöscht und ein neuer erstellt werden.

Anschließend ist der Access Token nutzbar - aber über die Gitlab-Web-Oberfläche nicht mehr ersichtlich, wie nachfolgende Bildschirmkopie zeigt:

Nachfolgende Beispiele zeigen den Aufbau für den Befehl curl und wie dieser dazu verwendet werden kann, Abfragen gegen die GitLab API durchzuführen.

Nachfolgende Erklärungen beschreiben den Aufbau des curl-Befehls-Syntax anhand dem nachfolgendem Beispiel:

# curl -s -u "user" --header "PRIVATE-TOKEN: j9rnycMbMSCyjKddBq8C" "https://serverC8.tachtler.net/api/v4/version" | python -mjson.tool
Enter host password for user 'user':

Erzeugt die Ausgabe der aktuellen Version von Gitlab:

• Siehe auch zur Beschreibung, den nachfolgenden externen Link: https://docs.gitlab.com/ee/api/version.html

{
    "revision": "c90ae59",
    "version": "11.5.1"
}

Nachfolgend der Befehlsaufbau:

HINWEIS - Der Paramater -u [username] muss nur angegeben werden, wenn ein .htaccess-Schutz besteht!

HINWEIS - Eine Passwortabfrage erfolgt nur, wenn der Paramerter -u [username] angegeben wurde!

HINWEIS - Die Passwortabfrage bezieht sich nur auf die .htaccess-Abfrage, falls vorhanden!

HINWEIS - Der Benutzer -u [username] aus der .htaccess-Abfrage kann vom Gitlab-Benutzer differieren!

HINWEIS - Der Gitlab-Benutzer wird nur durch den Access Token identifiziert!

Eine Liste der Möglichen Abfragen, kann unter nachfolgendem externen Link eingesehen werden:

• https://docs.gitlab.com/ee/api/README.html

*¹ HINWEIS - Ausserhalb der alphabetischen Reihenfolge, da dies ein Bestandteil für nachfolgende Befehle ist!

Nachfolgende Erklärungen beschreiben den Aufbau des curl-Befehls-Syntax zur Ermittlung aller Projekte aus Gitlab:

# curl -s -u "user" --header "PRIVATE-TOKEN: j9rnycMbMSCyjKddBq8C" "https://serverC8.tachtler.net/api/v4/projects/" | python -mjson.tool | grep -e \"id\" -e \"web_url\"
Enter host password for user 'user':

Erzeugt die Ausgabe der aktuellen Projekte von Gitlab:

• Siehe auch zur Beschreibung, den nachfolgenden externen Link: https://docs.gitlab.com/ee/api/projects.html

        "id": 8,
            "id": 2,
            "id": 2,
            "web_url": "https://serverC8.tachtler.net/gitlabuser"
        "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter",

Nachfolgend der Befehlsaufbau:

HINWEIS - Die Projekt-ID ist immer die am weitesten links stehende, hier: ”id”: 8, !

HINWEIS - Weiter eingerückte ID's sind die des „Parent“, hier: ”id”: 2, !

Nachfolgende Abfragen gegen die API beziehen sich auf den CI / CD Runner und dessen

• Pipelines API - https://docs.gitlab.com/ee/api/pipelines.html

HINWEIS - Zur Ermittlung der Projekt-ID - siehe nachfolgenden internen Link:

• Gitlab CentOS 7 - API (curl) - *¹ Project API

Nachfolgende Möglichkeiten der Informationsbeschaffung können durchgeführt werden:

Nachfolgende Erklärungen beschreiben den Aufbau des curl-Befehls-Syntax zur Auflistung aller Projektpipelines, eines bestimmten Projekts mit der entsprechenden Projekt-ID aus Gitlab:

# curl -s -u "user" --header "PRIVATE-TOKEN: j9rnycMbMSCyjKddBq8C" "https://serverC8.tachtler.net/api/v4/projects/8/pipelines" | python -mjson.tool
Enter host password for user 'user':

Erzeugt die Ausgabe der aktuellen Pipelines des Projekts 8 von Gitlab:

• Siehe auch zur Beschreibung, den nachfolgenden externen Link: https://docs.gitlab.com/ee/api/pipelines.html#list-project-pipelines

[
    {
        "id": 100,
        "ref": "development",
        "sha": "773b0e8bfb601567d38c9bda72e2b6fc9f614504",
        "status": "success",
        "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter/pipelines/100"
    },
    {
        "id": 99,
        "ref": "development",
        "sha": "2f16427b80aac4bb9afca89734243ab255762c9e",
        "status": "success",
        "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter/pipelines/99"
    },
    {
        "id": 98,
        "ref": "master",
        "sha": "477470a96c79e521a8cbd8f7282e73c2b15ea5e4",
        "status": "success",
        "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter/pipelines/98"
    },
    {
        "id": 97,
        "ref": "development",
        "sha": "0facb923e1d665d0b9b3604502b34cb765ef2232",
        "status": "success",
        "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter/pipelines/97"
    },
    {
        "id": 96,
        "ref": "development",
        "sha": "d5cd8f2a7c125d23adb6f5bfd2a07b78c73d67d3",
        "status": "success",
        "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter/pipelines/96"
    },
    {
        "id": 95,
        "ref": "development",
        "sha": "abc956e74618f26d76cdd87a4a226afd944103cc",
        "status": "failed",
        "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter/pipelines/95"
    },
    {
        "id": 94,
        "ref": "development",
        "sha": "e1b86374e5f04eb8ffa647295854d94e3bcaa013",
        "status": "failed",
        "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter/pipelines/94"
    }
]

Nachfolgende Erklärungen beschreiben den Aufbau des curl-Befehls-Syntax zur Auflistung einer Projektpipelines, eines bestimmten Projekts mit der entsprechenden Projekt-ID aus Gitlab:

# curl -s -u "user" --header "PRIVATE-TOKEN: j9rnycMbMSCyjKddBq8C" "https://serverC8.tachtler.net/api/v4/projects/8/pipelines/100" | python -mjson.tool
Enter host password for user 'user':

Erzeugt die Ausgabe einer Pipelines des Projekts 8 von Gitlab:

• Siehe auch zur Beschreibung, den nachfolgenden externen Link: https://docs.gitlab.com/ee/api/pipelines.html#get-a-single-pipeline

{
    "before_sha": "2f27427b80aac4bb9afca88734243bd25576229e",
    "committed_at": null,
    "coverage": null,
    "created_at": "2018-12-08T06:54:36.800Z",
    "duration": 8,
    "finished_at": "2018-12-08T06:54:48.963Z",
    "id": 100,
    "ref": "development",
    "sha": "772b0e8bfb601467d38c9cda72e2b6fc7f614504",
    "started_at": "2018-12-08T06:54:38.748Z",
    "status": "success",
    "tag": false,
    "updated_at": "2018-12-08T06:54:48.978Z",
    "user": {
        "avatar_url": null,
        "id": 2,
        "name": "Klaus Tachtler",
        "state": "active",
        "username": "gitlabuser",
        "web_url": "https://serverC8.tachtler.net/klaus"
    },
    "web_url": "https://serverC8.tachtler.net/gitlabuser/jmilter-footermilter/pipelines/100",
    "yaml_errors": null
}

HINWEIS - Erst ab Gitlab Version 11.6.x verfügbar!

Nachfolgende Erklärungen beschreiben den Aufbau des curl-Befehls-Syntax zur Löschung einer Projektpipelines, eines bestimmten Projekts mit der entsprechenden Projekt-ID aus Gitlab:

# curl -s -u "user" --header "PRIVATE-TOKEN: j9rnycMbMSCyjKddBq8C" --request "DELETE" "https://serverC8.tachtler.net/api/v4/projects/8/pipelines/100" | python -mjson.tool
Enter host password for user 'user':

Erzeugt die Ausgabe zur Löschung einer Pipelines des Projekts 8 von Gitlab:

• Siehe auch zur Beschreibung, den nachfolgenden externen Link: https://docs.gitlab.com/ee/api/pipelines.html#delete-a-pipeline

Nachdem alle GitLab API-Abfragen durchgeführt worden sind, kann der Access Token mit nachfolgendem Vorgehen widerrufen werden.

Nachfolgende Beschreibung zeigt, wie ein Access Token über die Gitlab-Web-Oberfläche widerrufen werden kann.

Nach erfolgreicher Anmeldung, muss im oberen Menü das Symbol für den Benutzer ausgewählt werden und dort der Menüpunkt [Settings] (Einstellungen) ebenfalls ausgewählt werden, wie nachfolgende Bildschirmkopie zeigt:

Anschließend wird im linken Bildschirmbereich der Menüpunkt [Access Tokens] ausgewählt, wie nachfolgende Bildschirmkopie zeigt:

Anschließend kann der Access Token in der Auflistung aller Access Token widerrufen werden, indem die Schaltfläche [Revoke], wie nachfolgende Bildschirmkopie zeigt:

Nachdem der Access Token widerrufen wurde, wird dies mit nachfolgender Anzeige bestätigt: