Automatische Tests mit GitLab CI

Das URZ bietet seit August 2015 die Versionsverwaltungsplattform GitLab im Pilotbetrieb an. Seit Version 8, die auch im URZ im Einsatz ist, können für Projekte eigene GitLab CI Runner definiert werden.

Ein CI Runner (von Continuous Integration) ist ein externes Stück Software, das bei jeder Aktualisierung eines Git-Repositories automatisch eine Menge vordefinierter Befehle ausführt und den Status zurück an den GitLab-Server des URZ übermittelt. In der GitLab-Weboberfläche wird das Ergebnis eines solchen Durchlaufs („Build“) dann grafisch dargestellt. Dieser Mechanismus kann dazu verwendet werden, automatisch eine Menge von Softwaretests auszuführen. Die auszuführenden Tests selbst sind ebenfalls Bestandteil des Git-Repositories und können im einfachsten Fall bereits aus nur einer Menge von Shell-Kommandos bestehen.

Natürlich kann ein GitLab CI Runner auch wesentlich mehr Aufgaben übernehmen. Dieser Blogeintrag soll aber zunächst anhand eines einfachen Beispiels zeigen, wie Sie GitLab CI für Ihre Projekte verwenden können, um automatisch Tests auszuführen.

Beispielprojekt

Als Beispiel gehen wir von einem Repository mit nur einer einzigen HTML-Datei aus, welche mit GitLab verwaltet und versioniert wird. Der dazugehörige Test prüft, ob die HTML-Datei auch tatsächlich gültiges HTML enthält. Dazu wird das Kommandozeilen-Werkzeug tidy verwendet.

Schritte

1. Installieren Sie GitLab CI Runner auf einem Rechner. Idealerweise verwenden Sie dafür bereits einen virtuellen Server. Unter Scientific Linux 7 genügt dazu folgendes Kommando:

   sudo yum install gitlab-ci-multi-runner

2. Installieren Sie das Program tidy auf dem gleichen Rechner. Unter Scientific Linux 7 ist das Programm ebenfalls über das Standard-Repository installierbar:

   sudo yum install tidy

3. Fügen Sie Ihrem Projekt die Datei .gitlab-ci.yml mit folgendem Inhalt zu:

   tidy_html:
     script:
       - tidy index.html
   

   Diese drei Zeilen stellen nun schon den eigentlichen Test dar. tidy_html ist nur der Name der Test-Suite und kann frei gewählt werden. script ist der Typ der Test-Suite und bedeutet in diesem Fall, dass der Test aus einer Menge von darauf folgenden Shell-Kommandos besteht. Der Typ script ist auch die einfachste Art, Tests und Kommandos mit GitLab CI auszuführen. Sobald einer der darauf folgenden Befehle fehlschlägt (Rückgabewert ungleich 0), gilt der Test als fehlgeschlagen.

   Die zum Test gehörenden Kommandos werden mit vier Leerzeichen eingerückt und einem darauf folgenden Bindestrich angegeben (YAML-Syntax).

   Wenn Sie nun das Projekt zu GitLab hochladen (git push) wird automatisch versucht, die Anweisungen in .gitlab-ci.yml zu befolgen.

4. Aktivieren Sie nun den GitLab CI Runner für Ihr Projekt in der GitLab-Weboberfläche. Gehen Sie dazu zunächst in die Einstellungen Ihres Projektes und überprüfen Sie, ob GitLab CI aktiviert ist (Project → Settings → Services → GitLab CI).
5. Registrieren Sie nun den auf Ihrer Maschine installierten Gitlab CI Runner für Ihr Projekt im URZ GitLab. Gehen Sie dazu zunächst in der GitLab-Weboberfläche Ihres Projektes auf Settings → Runners.
   Dort finden Sie unter Specific runners die notwendigen Parameter zur Konfiguration des CI Runners, den Sie auf Ihrem Rechner (oder virtuellen Server) betreiben. Führen Sie nun auf dem Rechner, auf dem Sie den Runner konfiguriert haben, folgenden Befehl aus:

   sudo gitlab-ci-multi-runner register

6. Außerdem werden Sie nach Folgendem gefragt:
   • gitlab-ci coordinator URL: Geben Sie hier die URL ein, die Ihnen in der GitLab-Weboberfläche angezeigt wird.
   • gitlab-ci token for this runner: Geben Sie hier das Token ein, das Ihnen in der GitLab-Weboberfläche angezeigt wird.
   • gitlab-ci description for this runner: Geben Sie hier einen Namen für den Runner ein (z. B. den Hostnamen). Dieser wird später in der GitLab- Weboberfläche angezeigt.
   • gitlab-ci tags for this runner (comma separated): Hier wird eine Liste von Tags erwartet, wie zum Beispiel html,shell.
   • executor: shell, parallels, docker, docker-ssh, ssh: Geben Sie hier für den ersten Test shell ein.

Nun werden nach jedem git push vom gerade definierten Runner die Shell-Befehle (in diesem Fall Tests) in .gitlab-ci.yml ausgeführt.

Natürlich lassen sich auch komplexere Tests, sowie automatische Software-Builds von einem GitLab CI Runner ausgeführt werden. Mit Docker ist es zum Beispiel möglich, in einem Container einen Webserver zu starten, der dann beispielsweise Webseiten ausliefert, die wiederum getestet werden können.

Fragen und Antworten

• Warum bietet das URZ keine öffentlichen CI Runner an?
  Die Umgebungen, in denen CI Runner betrieben werden können bzw. müssen, sind äußerst vielfältig. Häufig gleicht keine Umgebung der anderen, was es nahezu unmöglich macht, verschiedene Wünsche zu erfüllen. Auch die Verwendung von Docker-Containern kann dieses Problem nur bedingt lösen.
  Außerdem ermöglicht ein CI Runner letztendlich das Ausführen von beliebigen fremden Code, was unter sicherheitstechnischen Aspekten kritisch zu sehen ist. Daher raten wir Ihnen auch dazu, Ihre CI Runner nur für die Projekte freizuschalten, bei denen Sie allen teilnehmenden Nutzern vertrauen.
• Muss ich für GitLab CI Runner unbedingt einen Server beauftragen?
  Ein GitLab CI Runner kann auf jedem beliebigen Rechner ausgeführt werden. Sie können diesen daher auch auf einer Workstation oder sogar einem Laptop ausführen. Sollte der Rechner einmal offline sein, wird allerdings der Build-Status solange nicht aktualisiert, bis der Rechner wieder Netzkonnektivität hat und den Durchlauf starten kann. Für erste Tests reicht daher ein normaler Rechner, für die produktive Verwendung empfehlen wir allerdings einen virtuellen Server.