Inhaltsverzeichnis

Gitlab CentOS 7 - API (curl)

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

Beschreibung	Externer Link
Homepage	https://gitlab.com/
Dokumentation	https://about.gitlab.com/documentation/
Omnibus Doku.	https://docs.gitlab.com/omnibus/
Installation	https://about.gitlab.com/downloads/
Versionsvergleich	https://about.gitlab.com/features/#compare
API Dokumentation	https://docs.gitlab.com/ee/api/README.html

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:

Voraussetzungen

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

Vorbereitung

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.

Access Tokens: erstellen

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

Schritt 1

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:

Schritt 2

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

Schritt 3

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:

Feld	Standard Wert	Neuer Wert	Beschreibung
Name		`API Token`	Name des Access Token
Scopes	api	api ✔	Zugriff auf die api gestatten

Schritt 4

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.

Access Token
j9rnycMbMSCyjKddBq8C

Schritt 5

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

API: Abfragen

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:

Befehl/Paramater	Beschreibung
`curl`	Der Befehl `curl` selbst
`-s`	Silent - Unterdrückt jegliche Ausgaben die vom Befehl `curl` selbst sind
`-u ”[username]”`	User - (Benutzername) aus Gitlab
`−−header ”[token]”`	Access Token-Angabe für den Zugriff auf Gitlab
`[URL]`	URL mit Angabe der Informationen, welche ermittelt werden sollen
`\|`	Umleiten der Ausgabe in eine `pipe` (Kanal/Rohr) zu dem nachfolgendem Befehl
`python −mjson.tool`	Python-Befehlsaufruf zur JSON Formatierten Ausgabe

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

*¹ Project API

*¹ 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:

Befehl/Paramater	Beschreibung
`curl`	Der Befehl `curl` selbst
`-s`	Silent - Unterdrückt jegliche Ausgaben die vom Befehl `curl` selbst sind
`-u ”[username]”`	User - (Benutzername) aus Gitlab
`−−header ”[token]”`	Access Token-Angabe für den Zugriff auf Gitlab
`[URL]`	URL mit Angabe der Informationen, welche ermittelt werden sollen
`\|`	Umleiten der Ausgabe in eine `pipe` (Kanal/Rohr) zu dem nachfolgendem Befehl
`python −mjson.tool`	Python-Befehlsaufruf zur JSON Formatierten Ausgabe
`\|`	Umleiten der Ausgabe in eine `pipe` (Kanal/Rohr) zu dem nachfolgendem Befehl
`grep -e \”id\” -e \”web_url\”`	Filter der Ausgabe nach `”id”` und `”web_url”`

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, !

Pipelines API

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:

Möglichkeit	Externer Link
Auflistung der Projektpipelines	https://docs.gitlab.com/ee/api/pipelines.html#list-project-pipelines
Eine einzelne Pipeline abfragen	https://docs.gitlab.com/ee/api/pipelines.html#get-a-single-pipeline
Erstellen einer neuen Pipeline	https://docs.gitlab.com/ee/api/pipelines.html#create-a-new-pipeline
Wiederholung von Aufträgen in einer Pipeline	https://docs.gitlab.com/ee/api/pipelines.html#retry-jobs-in-a-pipeline
Abbrechen eines Pipeline-Auftrags	https://docs.gitlab.com/ee/api/pipelines.html#cancel-a-pipelines-jobs
Eine Pipeline löschen	https://docs.gitlab.com/ee/api/pipelines.html#delete-a-pipeline

Auflistung der Projektpipelines

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"
    }
]

Eine einzelne Pipeline abfragen

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
}

Eine Pipeline löschen

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

Nachbereitung

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

Access Token: widerrufen

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