GitLab CI: Dockerfile aus externem Repository einbinden – so geht’s

GitLab CI: Dockerfile aus externem Repository einbinden – so geht’s

Die zentrale Verwaltung von Build-Konfigurationen spart Zeit und reduziert Fehler. Doch wie können Teams einen Dockerfile in einem einzigen Repository speichern und in mehreren Projekten wiederverwenden? Die Lösung liegt in der Kombination von GitLab CI und der Repository Files API – ohne manuelle Kopien oder komplexe Submodule.

Das Problem: Wiederverwendung ohne Redundanz

In vielen Projekten gibt es ähnliche Abhängigkeiten: Frontend- und Backend-Teams benötigen identische Build-Prozesse. Die klassische Herangehensweise – ein Dockerfile pro Repository – führt zu Wartungsproblemen:

• Mehrfache Änderungen: Kleine Anpassungen müssen in jedem Projekt einzeln durchgeführt werden.
• Inkonsistenzen: Unterschiedliche Versionen des Dockerfiles werden genutzt.
• Veraltete Logik: Plattform-Teams verlieren die Kontrolle über die Build-Prozesse.

Ein zentrales Repository für CI/CD-Vorlagen scheint naheliegend, scheitert jedoch oft an der technischen Umsetzung. Der Befehl include:project importiert zwar die YAML-Konfiguration, nicht aber die Dateien selbst – und führt zu Fehlern wie Datei nicht gefunden.

Warum herkömmliche Lösungen scheitern

Die Versuchung ist groß, auf einfache – aber problematische – Lösungen zurückzugreifen:

• Kopieren des Dockerfiles in jedes Repository: Führt zu Redundanz und erschwert Updates.
• Git-Submodule: Komplex in der Handhabung und oft mit Berechtigungsproblemen verbunden.
• Annahme, dass `include` Dateizugriff ermöglicht: Ein weit verbreiteter Irrtum, der zu frustrierenden Fehlern führt.

Die eigentliche Herausforderung liegt darin, dass GitLab CI während der Pipeline-Ausführung in einem isolierten Umfeld arbeitet. Ohne gezielte Konfiguration hat der Job keinen Zugriff auf Dateien aus einem anderen Repository – selbst wenn die YAML-Konfiguration importiert wurde.

Die Lösung: CI_JOB_TOKEN und die GitLab Repository Files API

Die Lösung nutzt zwei zentrale Komponenten von GitLab CI:

1. CI_JOB_TOKEN: Ein temporärer Zugriffstoken, der während der Ausführung einer Pipeline generiert und automatisch an den Job übergeben wird. Dieser Token ist nur für die Dauer der Pipeline gültig und ermöglicht sichere API-Zugriffe.

1. GitLab Repository Files API: Eine REST-API, mit der Dateien aus einem Repository abgerufen werden können – vorausgesetzt, der Token hat die notwendigen Berechtigungen.

Schritt-für-Schritt-Anleitung

#### Schritt 1: Berechtigungen für Cross-Project-Zugriff einrichten Damit der Job auf das zentrale Dockerfile zugreifen kann, müssen die Berechtigungen in GitLab explizit konfiguriert werden:

1. Öffnen Sie das zentrale Repository (z. B. cicd-template).
2. Navigieren Sie zu Einstellungen → CI/CD → Job-Token-Berechtigungen.
3. Wählen Sie Fein granulare Berechtigungen → Repositories-Endpunkte.
4. Fügen Sie das Quellprojekt hinzu (z. B. kelvyn-labs/nextjs-cicd-template) zur Allowlist hinzu.

#### Schritt 2: Dockerfile aus dem zentralen Repository abrufen

In der Pipeline des Zielprojekts wird das Dockerfile zur Laufzeit abgerufen. Hier ein Beispiel für eine .gitlab-ci.yml:

variables:
  CICD_TEMPLATE_PROJECT_ID: "81568045"  # Projekt-ID des zentralen Repositories
  CICD_TEMPLATE_REF: "main"              # Branch oder Tag (z. B. "v1.0.0")
  CICD_TEMPLATE_DOCKERFILE_PATH: "frontend%2FDockerfile"  # URL-codierter Pfad

.build-job:
  script:
    - echo "Dockerfile wird aus zentralem Repository abgeholt..."
    - |-
      curl --fail --location \
        --header "JOB-TOKEN: $CI_JOB_TOKEN" \
        " \
        -o Dockerfile

Wichtige Hinweise:

• Der Dateipfad muss URL-codiert werden (z. B. frontend/Dockerfile → frontend%2FDockerfile).
• Die Projekt-ID ist einfacher zu handhaben als die manuelle Kodierung des Pfads.
• Der Token ist nur während der Pipeline-Ausführung gültig.
• Das Ziel-Repository muss den Zugriff explizit erlauben (siehe Schritt 1).

#### Schritt 3: Docker-Image mit dem abgerufenen Dockerfile erstellen

Sobald das Dockerfile lokal vorliegt, kann es im Build-Prozess verwendet werden:

docker buildx build \
  --file Dockerfile \
  --tag registry.example.com/myapp:$CI_COMMIT_SHORT_SHA \
  --push .

Vorteile dieser Methode

Die zentrale Verwaltung von Dockerfiles über GitLab CI bietet mehrere entscheidende Vorteile:

• Zentrale Kontrolle: Das Plattform-Team verwaltet das Dockerfile an einer einzigen Stelle.
• Keine Duplikate: Keine manuellen Kopien in verschiedenen Projekten.
• Sicherheit: Zugriff nur mit expliziter Berechtigung und temporärem Token.
• Flexibilität: Funktioniert für Frontend, Backend und beliebige andere Services.

Wann diese Lösung NICHT geeignet ist

Es gibt Szenarien, in denen diese Methode nicht optimal ist:

• Mehrere abhängige Dateien: Wenn das Dockerfile auf andere Dateien (z. B. scripts/start.sh) verweist, ist ein vollständiges git clone des Ziel-Repositories sinnvoller.
• Komplexe Abhängigkeitsstrukturen: Bei vielen verknüpften Dateien wird die manuelle Verwaltung der Pfade unübersichtlich.

Praktische Tipps für die Umsetzung

1. Versionierung festlegen: Nutzen Sie statt main oder master einen spezifischen Tag (z. B. v1.2.0), um Build-Konsistenz zu gewährleisten.

1. Variablen zentralisieren: Definieren Sie häufig genutzte Werte wie Projekt-ID und Dateipfad als Variablen, um die Wartbarkeit zu erhöhen.

1. Fehlerbehandlung einbauen: Prüfen Sie den Erfolg des API-Aufrufs mit --fail, um Pipeline-Fehler frühzeitig zu erkennen.

Fazit: CI/CD als Plattform denken

Die Wiederverwendung von Build-Konfigurationen über mehrere Projekte hinweg ist ein zentraler Baustein moderner DevOps-Strategien. Mit GitLab CI und der Repository Files API können Teams Dockerfiles zentral verwalten – ohne Redundanz, mit voller Kontrolle und maximaler Sicherheit.

Die nächste Generation der CI/CD-Pipelines wird nicht mehr durch manuelle Kopien, sondern durch intelligente API-Integration und Plattformdenken geprägt sein. Nutzen Sie diese Technologie, um Ihre Build-Prozesse zu standardisieren und effizienter zu gestalten.

Weiterführende Ressourcen:

• GitLab-Dokumentation: Fein granulare Berechtigungen
• GitLab API: Repository Files
• Beispiel-Repositories auf GitLab
• Vorlage für Next.js-Projekte