Eigenen GitLab Runner installieren und registrieren

1. Warum ein eigener GitLab Runner statt Shared Runner

GitLab stellt auf gitlab.com Shared Runner zur Verfügung, die sofort nutzbar sind — ohne Installation, ohne Konfiguration. Für viele Projekte ist das ausreichend, besonders für Open-Source-Projekte, deren Build keine sensiblen Netzwerkressourcen oder spezielle Tools braucht. Für professionelle Magento-Projekte greifen die Shared Runner jedoch an drei kritischen Punkten zu kurz: Sicherheit, Performance und Zugriff auf interne Ressourcen.

Bei Sicherheit: Shared Runner führen Jobs für alle GitLab-Nutzer aus. Ein Magento-Deployment-Job braucht SSH-Schlüssel zum Produktionsserver, Composer-Auth-Tokens für private Packages und möglicherweise Datenbankzugänge für Setup-Upgrade. Diese Secrets auf einem Shared Runner zu verwenden bedeutet, dass sie in einer Umgebung laufen, die nicht ausschließlich unter der eigenen Kontrolle steht. Ein Self-hosted Runner läuft ausschließlich für das eigene Projekt auf einem selbst verwalteten Host.

Bei Performance: Magento-Builds mit Composer-Install und DI-Kompilierung dauern ohne Cache mehrere Minuten. Ein eigener Runner kann den Composer-Cache über Jobs hinweg persistieren, was Build-Zeiten erheblich reduziert. Shared Runner starten typischerweise in frischen Containern ohne persistenten Cache. Zusätzlich können Build-Ressourcen (CPU, RAM) auf dem eigenen Runner an die tatsächliche Last angepasst werden, ohne auf das Ressourcen-Budget geteilter Systeme angewiesen zu sein.

2. Voraussetzungen und Host-Wahl

Für einen GitLab Runner mit Docker-Executor werden drei Voraussetzungen benötigt: ein Linux-Server (Debian, Ubuntu oder RHEL-basierte Distributionen werden offiziell unterstützt), Docker in einer aktuellen stabilen Version und Netzwerkzugang zu gitlab.com oder der eigenen GitLab-Instanz. Der Runner-Host muss nicht derselbe sein wie der Deployment-Zielserver — es empfiehlt sich sogar, diese Hosts zu trennen, damit ein kompromittierter Runner keinen direkten Dateisystemzugriff auf den Produktionsserver hat.

Die Hardware-Anforderungen hängen von der Build-Last ab. Für einen einzelnen Magento-Build empfehlen sich mindestens zwei CPU-Kerne und vier Gigabyte RAM. Wer mehrere gleichzeitige Builds unterstützen will, skaliert entsprechend. Der persistente Composer-Cache kann mehrere Gigabyte erreichen, weshalb ausreichend Speicherplatz für Docker-Images, Build-Caches und Artefakte eingeplant werden sollte.

# Runner host requirements — verify before installation
# Run these checks on the target Linux server

# 1. Check OS version
cat /etc/os-release

# 2. Install Docker if not present (Ubuntu/Debian)
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor \
  -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
  | tee /etc/apt/sources.list.d/docker.list
apt-get update && apt-get install -y docker-ce docker-ce-cli containerd.io

# 3. Verify Docker installation
docker --version
docker run --rm hello-world

# 4. Check network connectivity to GitLab
curl -fsSL https://gitlab.com > /dev/null && echo "GitLab reachable"

3. Runner-Installation auf Linux

Die Installation des GitLab-Runners folgt dem offiziellen Paketrepository von GitLab. Das ist die empfohlene Installationsmethode, weil Updates über den Paketmanager verwaltet werden können. Alternativ steht ein Binary-Download zur Verfügung, der aber manuelle Update-Pflege erfordert. Für Produktionssysteme ist das Paketrepository vorzuziehen, weil es Sicherheits-Updates einfacher macht.

Nach der Installation läuft der Runner-Dienst als Systemd-Service und startet automatisch nach einem Neustart. Der Dienst-Status kann jederzeit mit systemctl status gitlab-runner geprüft werden. Die Log-Ausgabe des Runners ist für die Fehlersuche wichtig und liegt standardmäßig in den Systemd-Journals, erreichbar mit journalctl -u gitlab-runner -f.

4. Runner registrieren mit Docker-Executor

Die Registrierung verknüpft den installierten Runner mit einem GitLab-Projekt oder einer Gruppe. Dazu braucht man einen Registration-Token, der in den GitLab-Projekteinstellungen unter CI/CD → Runners zu finden ist. Seit GitLab 16 wird die Registrierung über Authentication-Tokens statt über Registration-Tokens bevorzugt — die Benutzeroberfläche zeigt den aktuellen Weg an.

Der Docker-Executor ist für die meisten Magento-Build-Jobs die beste Wahl. Jeder Job startet in einem frischen Docker-Container mit dem in .gitlab-ci.yml definierten Image, was Reproduzierbarkeit garantiert. Der Shell-Executor bietet direkte Ausführung auf dem Host, was schneller ist, aber Abhängigkeiten auf dem Runner-Host voraussetzt. Für Deploy-Jobs, die SSH-Verbindungen aufbauen müssen, kann der Shell-Executor sinnvoller sein, da er keinen privilegierten Docker-Modus braucht.

# GitLab Runner registration — Docker executor
# Run on the runner host after installation

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --executor "docker" \
  --docker-image "php:8.4-cli" \
  --description "magento-build-runner" \
  --tag-list "magento,php84,docker" \
  --run-untagged "false" \
  --locked "false" \
  --docker-volumes "/cache/composer:/root/.composer:rw" \
  --docker-volumes "/cache/npm:/root/.npm:rw" \
  --docker-pull-policy "if-not-present"

# Verify registration was successful
gitlab-runner verify

# Check runner status
gitlab-runner status

5. config.toml verstehen und anpassen

Die Konfigurationsdatei /etc/gitlab-runner/config.toml enthält alle Runner-Einstellungen und kann nach der Registrierung manuell angepasst werden. Änderungen werden vom Runner-Prozess automatisch erkannt, ohne dass ein Neustart notwendig ist. Wichtige Einstellungen: concurrent auf globaler Ebene bestimmt die maximale Anzahl gleichzeitiger Jobs über alle Runner-Instanzen. limit pro Runner beschränkt die Anzahl gleichzeitiger Jobs für diesen spezifischen Runner.

Für Deployment-Runner empfiehlt sich limit = 1, um Race Conditions bei gleichzeitigen Deployments auf denselben Server zu verhindern. Für Build-Runner kann ein höherer Wert gesetzt werden, um parallele Builds zu unterstützen. Docker-Volume-Mounts für Caches sollten persistent sein und außerhalb des Container-Filesystems liegen, damit sie zwischen Job-Ausführungen erhalten bleiben.

6. Runner-Tags und Job-Zuordnung

Runner-Tags sind das Routing-System zwischen GitLab-Jobs und Runner-Instanzen. Ein Job mit tags: [magento, production] wird nur auf Runnern ausgeführt, die beide Tags haben. Ohne Tags läuft ein Job auf jedem Runner, der für run-untagged-Jobs konfiguriert ist. Für Produktionsumgebungen sollte run-untagged auf false gesetzt sein, damit keine unerwünschten Jobs auf dem Runner landen.

Ein sinnvolles Tag-Schema für Magento-Projekte trennt Build-Runner von Deploy-Runnern. Der Build-Runner bekommt Tags wie magento und php84. Der Deploy-Runner, der SSH-Zugang zum Produktionsserver hat, bekommt einen separaten Tag wie magento-deployer. Diese Trennung stellt sicher, dass ein kompromittierter Build-Job keinen automatischen Zugang zu Deploy-Secrets bekommt.

7. Sicherheitsrichtlinien für den Runner

Der Runner-Host ist Teil der sicherheitskritischen Infrastruktur eines Teams. Er hat Zugang zu SSH-Schlüsseln, Composer-Auth-Tokens und möglicherweise Datenbankzugangsdaten. Deshalb gelten für den Runner-Host dieselben Sicherheitsanforderungen wie für Server in der Produktionsumgebung: regelmäßige System-Updates, minimale offene Ports, SSH-Zugang nur über Key-Authentifizierung und kein direktes Root-Login.

Im Docker-Executor dürfen Jobs niemals mit privilegierten Containern ausgeführt werden, es sei denn, es ist explizit notwendig und gut begründet. privileged = false in der config.toml verhindert, dass Jobs den Docker-Daemon des Hosts ansprechen oder Kernel-Capabilities beanspruchen. Secrets sollten nie als Docker-Environment-Variablen übergeben werden, wenn sie in Container-Logs erscheinen könnten — die Masked-Flag in GitLab CI/CD-Variablen ist Pflicht für alle sensiblen Werte.

# config.toml — secure runner configuration for Magento
# Location: /etc/gitlab-runner/config.toml

concurrent = 4
check_interval = 0
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "magento-build"
  url = "https://gitlab.com/"
  token = "[REGISTERED_TOKEN]"
  executor = "docker"
  # Restrict to tagged jobs only — no untagged job pickup
  run_untagged = false
  # Allow only one concurrent deploy per runner instance
  limit = 1

  [runners.docker]
    tls_verify = false
    image = "php:8.4-cli"
    # Never run privileged containers
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    # Mount persistent caches outside container filesystem
    volumes = [
      "/cache/composer:/root/.composer:rw",
      "/cache/npm:/root/.npm:rw",
      "/tmp/gitlab-runner-build:/build:rw"
    ]
    pull_policy = "if-not-present"
    shm_size = 0

8. Magento-spezifische Runner-Konfiguration

Für Magento-Builds gibt es einige Konfigurationspunkte, die die Build-Zeit erheblich reduzieren. Der persistente Composer-Cache ist der wichtigste: Wenn /root/.composer zwischen Jobs erhalten bleibt, werden Composer-Pakete beim zweiten Build aus dem Cache geladen statt heruntergeladen. Für ein typisches Magento-Projekt mit vielen Abhängigkeiten kann das den Composer-Install-Schritt von mehreren Minuten auf Sekunden reduzieren.

DI-Kompilierung (setup:di:compile) ist rechenintensiv. Auf einem Runner mit genug CPU-Kernen läuft sie schnell, auf einem Single-Core-System kann sie über zehn Minuten dauern. Wenn die DI-Kompilierung zu langsam ist, empfiehlt sich entweder ein leistungsfähigerer Runner oder das Cachen des generierten Codes über GitLab-CI-Cache auf Basis des Composer-Lock-Hash. Frontend-Builds mit Tailwind CSS profitieren ebenfalls von einem persistenten npm-Cache.

9. Runner-Wartung und Updates

Der GitLab-Runner muss regelmäßig aktualisiert werden. GitLab empfiehlt, den Runner innerhalb einer Major-Version des GitLab-Servers zu halten. Wer GitLab 17.x verwendet, sollte einen Runner der Version 17.x einsetzen. Updates über den Paketmanager sind einfach und risikoarm: apt-get update && apt-get install gitlab-runner bringt den Runner auf die aktuelle Version.

Regelmäßige Wartungsaufgaben umfassen das Bereinigen alter Docker-Images und -Container auf dem Runner-Host, das Überwachen des Speicherplatzverbrauchs des Composer-Caches und das Prüfen der Runner-Logs auf Fehler oder auffällige Muster. Ein Runner, der regelmäßig in Timeout-Fehler läuft, weist auf Ressourcenprobleme oder Netzwerkprobleme hin, die frühzeitig behoben werden sollten.

10. Zusammenfassung

Ein eigener GitLab Runner gibt Magento-Teams die Kontrolle über Build-Umgebung, Sicherheit, Performance und Zugriffspfade, die Shared Runner nicht bieten können. Die Installation ist unkompliziert und folgt dem offiziellen Paketrepository. Der Docker-Executor ist für Build-Jobs die beste Wahl, weil er Reproduzierbarkeit durch Container-Isolation garantiert. Die Registrierung verknüpft den Runner mit dem GitLab-Projekt und erlaubt feingranulare Steuerung über Tags und Concurrency-Limits.

Sicherheit ist nicht optional: Der Runner-Host muss wie ein produktionskritischer Server behandelt werden. Kein privilegierter Docker-Modus ohne expliziten Grund, keine Shared Runner für Deploy-Jobs mit Produktionsgeheimnissen, Masked-Flag für alle sensiblen Variablen. Persistente Caches für Composer und npm reduzieren Build-Zeiten messbar. Regelmäßige Updates und Monitoring stellen sicher, dass der Runner zuverlässig bleibt.

11. FAQ: GitLab Runner installieren und registrieren

Ein sauber konfigurierter eigener Runner ist die Basis für schnelle, reproduzierbare und sichere Deployments — er amortisiert sich schon nach wenigen Projekten durch wegfallende Wartezeiten auf Shared-Runner-Slots und vollständige Kontrolle über die Ausführungsumgebung.