GitLab CI

In diesem zweiteiligen Artikel werden wir die Continuous Integration Funktionalitäten von GitLab CI genauer unter die Lupe nehmen.

Der erste Teil widmet sich der Installation und Konfiguration, während der zweite Teil detaillierter auf einzelne Anwendungsszenarien eingehen wird.

Was ist CI überhaupt?

CI steht in diesem Fall für Continous Integration und bedeutet vereinfacht gesagt, dass nach jeder Änderung am Source Code eines Projektes ein Script ausgeführt wird.
Das CI-Script wird in den meisten Fällen über eine Versionsverwaltung getriggert. Dateien welche dieses Script erstellt, können später als sogenannte Build Artifacts weiterverwendet werden.

In vielen Fällen startet dieses Script Unit-Tests, welche überprüfen, ob die soeben gemachten Änderungen nicht unbeabsichtigt andere Teile des Projektes beeinflussen.
Unit-Tests sind jedoch nur ein Szenario, ein CI kann beispielsweise auch Pakete bauen, Dokumentationen erstellen oder sogar Anwendungen deployen.

GitLab CI

GitLab ist eine Open Source Lösung für Git-Hosting, die unter anderem auch CI-Funktionalität bietet. Seit Version 8.2 ist der CI-Teil fest in GitLab integriert und muss nicht mehr wie zuvor auf einem separaten Server installiert werden.

Das Konzept von GitLab CI basiert auf so genannten Runnern, welche die eigentlichen Build-Scripts ausführen. GitLab CI ist nur für das Orchestrieren dieser Runner und dem Zusammentragen von Resultaten und Artifacts zuständig. Runner können Docker-Container, VMs oder auch bare metal Maschinen sein, die optimalerweise nicht auf demselben Server wie der Orchestrator ausgeführt werden. Dadurch haben die CI-Scripte kein Zugriff auf GitLab selbst.

Die Runner melden sich alle paar Sekunden über HTTPS bei GitLab und fragen nach, ob es für sie einen Job gibt, GitLab CI kann die Runner von sich aus nicht kontaktieren.
Dies erleichtert die Einrichtung von neuen Runnern erheblich, einzige Voraussetzung ist, dass sich der Runner per HTTPS mit GitLab verbinden kann.

Die Runner-Komponente von GitLab nennt sich gitlab-ci-multi-runner [1] und ist ein statisch kompiliertes Binary, welches neben Linux auch Builds auf Windows, OSX und BSD unterstützt.

Das CI-Script für GitLab muss im Hauptverzeichnis des jeweiligen Repos liegen und den Dateinamen .gitlab-ci.yml haben.

CI für ein Projekt aktivieren

Seit Version 8.2 ist die CI-Komponente in GitLab integriert und standardmässig aktivert. Sie kann jedoch auch nur für einzelne Projekte aktiviert bzw. deaktiviert werden.
Die Einstellung nennt sich Builds und ist in den Projekteinstellungen unter Features zu finden:

GitLab löscht keine bereits ausgeführten Builds und Artifacts wenn das Feauture deaktiviert wird, sondern versteckt nur den Menüpunkt Builds.

Unter gitlab.example.com/group/repo/builds sind diese weiterhin einsehbar. Builds zu löschen ist über das Webinterface machbar. Seit GitLab 8.9 ist es möglich im .gitlab-ci.yml zu konfigurieren, wie lange die Resultate und Artifacts aufbewahrt werden. [2]

Runner

Setup

Nach dem Aktivieren von CI im Webinterface, muss ein Runner eingerichtet werden, welcher die effektiven Builds ausführt. In diesem Beispiel wird gitlab-ci-multi-runner auf einer Debian Jessie VM mit dem Docker-Executor eingerichtet. Im zweiten Teil dieses Artikels wird detaillierter auf weitere Runner-Konfigurationen eingegangen.

Als erster Schritt sollte das System aktualisiert werden:

# apt-get update
# apt-get upgrade

Da Docker-Runner verwendet werden, braucht es entsprechend Docker:

# curl -sSL https://get.docker.com/ | sh

GitLab stellt ein Script zur Verfügung, welches das Repository automatisch konfiguriert. Dies kann mit folgendem Kommando ausgeführt werden:

# curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh | sudo bash

Wer keine Scripte aus dem Internet unkontrolliert ausführen möchte, kann das Repo auch auf den traditionellen Weg aktivieren:

# echo "deb https://packages.gitlab.com/runner/gitlab-ci-multi-runner/debian/ jessie main" >> /etc/apt/sources.list
# wget -qO - https://packages.gitlab.com/gpg.key | apt-key add -
# apt-get update

Anschliessend kann gitlab-ci-multi-runner über APT installiert werden:

# apt-get install gitlab-ci-multi-runner

Dies richtet einen systemd-Dienst ein, welcher (auf Debian Systemen) per Default aktiviert und gestartet sein sollte:

# systemctl status gitlab-runner.service
● gitlab-runner.service - GitLab Runner
Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled)
Active: active (running) since Mon 2016-09-19 18:33:32 CEST; 1 weeks 0 days ago
Main PID: 28102 (gitlab-ci-multi)
CGroup: /system.slice/gitlab-runner.service
└─28102 /usr/bin/gitlab-ci-multi-runner run --working-directory /home/gitlab-runner --config /etc/gitlab-runner/config.toml --service gitlab-runner --syslog...

Der Runner ist nun bereit und kann in Projekten registriert und verwendet werden.

Runner registrieren

Der neu installierte Runner muss nun in GitLab registriert werden. Jedes Projekt hat hierzu ein eindeutiges Runner-Token, welches im Webinterface unter Project Settings > Runner eingesehen werden kann:

Mit diesem Token kann der zuvor eingerichtete Runner aktiviert werden. Dazu auf der Runner-VM folgendes Kommando eingeben:

# gitlab-ci-multi-runner register \
--url gitlab.example.com
--registration-token L4zpDbiAAA86sDnvYPkn \
--description "CI hello world" \
--executor "docker" \
--docker-image debian:jessie

Parameter:

  • --url GitLab CI URL
  • --registration-token Registration Token
  • --description Beschreibung des Runners
  • --executor Executor, in diesem Fall Docker
  • --docker-image Docker-Image, unter dem der Runner läuft. In diesem Beispiel wird ein Jessie-Container als Runner verwendet.

Der Runner sollte nach einigen Sekunden im Webinterface erscheinen:

.gitlab-ci.yml

Nachdem der Runner eingerichtet und registriert ist, muss das .gitlab-ci.yml im Hauptverzeichnis des Projektes erstellt werden. In unserem Beispiel wird nur eine Datei erstellt und getestet, ob diese vorhanden ist:

stages:
- test

run-test:
stage: test
script:
- touch foo
- test foo

Nach dem Commiten und Pushen sollte unter Builds bereits ein laufender Build erscheinen:

Der Build sollte bereits nach einigen Sekunden abgschlossen sein:

Ausblick

Im zweiten Teil werden wir detaillierter auf Real-Life Anwendungsszenarien eingehen und weitere Runner-Typen vorstellen.

Referenzen


  1. https://gitlab.com/gitlab-org/gitlab-ci-multi-runner
  2. https://docs.gitlab.com/ce/ci/yaml/README.html#artifactsexpire_in