30 GitLab CI Yaml Syntax

30.1 Global Keywords

In der YAML-Datei von GitLab CI gibt es globale Keywords, die auf alle Jobs in einer Pipeline angewendet werden und somit eine einheitliche Struktur und Konfiguration ermöglichen. Diese globalen Einstellungen erleichtern die Verwaltung, besonders bei größeren Pipelines, da sie eine Wiederholung von Konfigurationen in jedem Job vermeiden. Die zentralen globalen Keywords sind:

30.1.1 before_script und after_script

• before_script: Definiert eine Liste von Befehlen, die vor jedem Job ausgeführt werden, es sei denn, ein Job überschreibt diese Definition. Diese Befehle können für das Setzen von Umgebungsvariablen oder für Installationen von Abhängigkeiten genutzt werden, die für alle Jobs gelten.

  Beispiel:

  before_script:
    - echo "Setting up the environment"
    - apt-get update -y

• after_script: Analog zu before_script werden die im after_script definierten Befehle nach jedem Job ausgeführt, unabhängig davon, ob der Job erfolgreich war oder nicht. Es wird oft für Aufräumarbeiten verwendet, wie das Schließen von Verbindungen oder das Löschen temporärer Dateien.

  Beispiel:

  after_script:
    - echo "Cleaning up after the job"
    - rm -rf /tmp/*

  Diese Befehle werden nach jedem Job ausgeführt und tragen dazu bei, eine saubere Umgebung für die nächsten Jobs zu gewährleisten.

30.1.2 image

• image: Definiert das Docker-Image, in dem der Job ausgeführt wird. Docker-Images ermöglichen es, eine konsistente Umgebung für die Ausführung der Jobs bereitzustellen. Wenn kein Image pro Job definiert wird, greift die Pipeline auf dieses globale Image zurück.

  Beispiel:

  image: ruby:2.7

  In diesem Beispiel wird jeder Job innerhalb eines Ruby 2.7 Docker-Containers ausgeführt, sofern der Job kein eigenes Image spezifiziert.

30.1.3 services

• services: Definiert zusätzliche Docker-Container, die während des Jobs ausgeführt werden, z. B. Datenbanken oder Cache-Systeme. Diese Container laufen parallel zum Hauptcontainer und sind für den Job verfügbar.

  Beispiel:

  services:
    - postgres:latest

  Hier wird ein PostgreSQL-Container bereitgestellt, der während der Jobausführung zur Verfügung steht. Dies ist besonders nützlich für Jobs, die auf eine Datenbank oder einen Service zugreifen müssen.

30.1.4 stages

• stages: Definiert die verschiedenen Phasen einer Pipeline, die in der Reihenfolge ausgeführt werden, wie sie hier festgelegt sind. Jeder Job gehört zu einer Phase, und Jobs in derselben Phase werden parallel ausgeführt.

  Beispiel:

  stages:
    - build
    - test
    - deploy

  Die Phasen legen fest, in welcher Reihenfolge Jobs ausgeführt werden. So kann beispielsweise der build-Job erst abgeschlossen werden, bevor die test-Phase beginnt.

30.1.5 variables

• variables: Definiert benutzerdefinierte CI/CD-Variablen, die in der gesamten Pipeline verwendet werden können. Diese Variablen können verwendet werden, um Umgebungsparameter, wie Pfade oder Zugangsschlüssel, zentral zu definieren und an alle Jobs weiterzugeben.

  Beispiel:

  variables:
    DATABASE_URL: "postgres://user:pass@localhost:5432/db"

  Hier wird eine Umgebungsvariable für die Datenbankverbindung definiert, die in allen Jobs der Pipeline verfügbar ist.

30.1.6 cache

• cache: Speichert Verzeichnisse und Dateien zwischen verschiedenen Jobs und Pipelines, um Zeit zu sparen. Typische Anwendungsfälle sind das Zwischenspeichern von Abhängigkeiten oder Build-Artefakten.

  Beispiel:

  cache:
    paths:
      - node_modules/

  Dies speichert das node_modules-Verzeichnis zwischen den Jobs und verhindert so das wiederholte Herunterladen von Abhängigkeiten.

30.1.7 artifacts

• artifacts: Speichert Dateien und Verzeichnisse nach Abschluss eines Jobs, sodass nachfolgende Jobs oder Pipelines diese verwenden können. Dies wird häufig verwendet, um Build-Artefakte oder Testberichte zu speichern.

  Beispiel:

  artifacts:
    paths:
      - build/

  Hier werden die erstellten Build-Dateien nach Abschluss des Jobs gespeichert, sodass sie für nachfolgende Jobs verfügbar sind.

Weitere Informationen finden sich in der GitLab Dokumentation zu Global Keywords.

30.2 Header Keywords in GitLab CI YAML

Die Header Keywords in der GitLab CI .gitlab-ci.yml-Datei definieren allgemeine Einstellungen und Vorgaben für alle Jobs oder auch für spezifische Gruppen von Jobs. Diese Schlüsselwörter sind essenziell, um die Ausführungsumgebung, Limits und Verhalten für alle Jobs einer Pipeline einheitlich zu steuern.

30.2.1 default

• default: Mit diesem Schlüsselwort können Standardwerte definiert werden, die für alle Jobs der Pipeline gelten, es sei denn, sie werden explizit in einem Job überschrieben. Dies reduziert Wiederholungen und stellt sicher, dass die Jobs konsistent konfiguriert sind.

  Beispiel:

  default:
    image: ruby:2.7
    before_script:
      - bundle install

  In diesem Beispiel wird für alle Jobs das Docker-Image ruby:2.7 verwendet, und der Befehl bundle install wird vor jedem Job ausgeführt.

30.2.2 include

• include: Ermöglicht das Einbinden zusätzlicher YAML-Dateien in die .gitlab-ci.yml, sodass Konfigurationen wiederverwendet oder über mehrere Projekte hinweg geteilt werden können. Dies ist besonders nützlich, um große oder komplexe Pipelines modular zu gestalten.

  Es gibt verschiedene Methoden, um YAML-Dateien einzubinden:

  • Remote: Eine externe URL, von der die YAML-Datei geladen wird.
  • Local: Eine Datei innerhalb desselben Projekts.
  • Template: GitLab CI Templates.

  Beispiel:

  include:
    - project: 'my-group/my-shared-config'
      file: '/ci-templates/common.yml'

  Hier wird eine YAML-Datei aus einem anderen Projekt eingebunden, um eine gemeinsame Konfiguration zu nutzen.

30.2.3 extends

• extends: Erlaubt es, Konfigurationen von einem anderen Job oder einer Gruppe von Jobs zu erben und zu erweitern. Dies ist hilfreich, um gemeinsame Jobs zu definieren und diese anschließend anzupassen, ohne sie komplett neu schreiben zu müssen.

  Beispiel:

  .base-job:
    script:
      - echo "Running base job"
  
  test-job:
    extends: .base-job
    script:
      - echo "Running test job"

  Hier erbt der test-job den Skriptabschnitt des base-job und fügt zusätzliche Befehle hinzu.

30.2.4 workflow

• workflow: Bestimmt, wann Pipelines basierend auf Regeln und Bedingungen ausgelöst werden. Es ist ein flexibles Werkzeug, um komplexe Logiken für das Auslösen von Pipelines zu definieren, z. B. durch Commit-Nachrichten, Branches oder Zeitpläne.

  Beispiel:

  workflow:
    rules:
      - if: '$CI_COMMIT_BRANCH == "main"'
      - if: '$CI_PIPELINE_SOURCE == "schedule"'

  In diesem Beispiel wird die Pipeline nur ausgelöst, wenn der aktuelle Branch main ist oder die Pipeline über einen Zeitplan gestartet wurde.

30.2.5 types (veraltet)

• types: Früher wurde dieses Keyword verwendet, um die Art von Jobs zu definieren. Es ist mittlerweile veraltet und wurde durch das stages-Keyword ersetzt. Alte Konfigurationen, die types nutzen, sollten aktualisiert werden, um moderne Pipelines zu unterstützen.

Weitere Details finden sich in der GitLab Dokumentation zu Header Keywords.