GitLab Runner Typen: Shell, Docker, Kubernetes – wann was für Magento passt

1. Was ist ein GitLab Runner?

Ein GitLab Runner ist ein Prozess, der auf einer Maschine läuft, sich bei einer GitLab-Instanz registriert und dort verfügbar ist, um Pipeline-Jobs auszuführen. GitLab selbst führt keine Jobs aus – es delegiert die Ausführung an registrierte Runner. Der Runner empfängt Job-Definitionen von GitLab, führt die definierten Scripts aus, sammelt Logs und Artefakte und meldet das Ergebnis zurück an GitLab. Ohne mindestens einen Runner kann keine Pipeline laufen.

Runner sind über Executors konfiguriert – das ist der Mechanismus, mit dem der Runner entscheidet, wie er einen Job ausführt. Die drei wichtigsten Executors sind: Shell (direkt auf dem Host-Betriebssystem), Docker (in einem Container, der für jeden Job neu gestartet wird) und Kubernetes (als Pod in einem Kubernetes-Cluster). Jeder Executor hat unterschiedliche Eigenschaften bezüglich Isolation, Reproduzierbarkeit, Performance und Sicherheit. Die Wahl des Executors ist eine der wichtigsten Entscheidungen beim Setup einer GitLab-Pipeline.

Runner können auf drei Ebenen registriert werden: Projekt-Runner sind nur für ein spezifisches Projekt verfügbar. Gruppen-Runner sind für alle Projekte in einer GitLab-Gruppe verfügbar. Instanz-Runner (früher Shared Runner) sind für alle Projekte der GitLab-Instanz verfügbar. GitLab.com bietet öffentliche Shared Runner, die für einfache Build-Jobs geeignet sind, aber für Production-Deployments auf eigene Server nicht empfohlen werden.

2. Shell-Executor: direkt auf dem Host

Der Shell-Executor führt Pipeline-Jobs direkt auf dem Betriebssystem des Runner-Hosts aus, im Kontext des Benutzers, unter dem der Runner-Prozess läuft. Das ist die einfachste Konfiguration: kein Container, keine Virtualisierung, keine Image-Downloads. Die Ausführungsumgebung ist statisch – was auf dem Runner-Host installiert ist, steht allen Jobs zur Verfügung. Für Magento-Deployments, bei denen SSH-Zugriff auf Zielserver benötigt wird, ist der Shell-Executor oft die praktische Wahl.

Der wesentliche Nachteil des Shell-Executors ist die fehlende Isolation: Jobs laufen im selben Benutzerkontext und teilen sich das Dateisystem des Hosts. Wenn zwei Jobs gleichzeitig laufen und auf dieselben Dateien zugreifen, entstehen Race Conditions. Außerdem akkumuliert der Shell-Executor über Zeit Zustände – installierte Pakete, gecachte Dateien, Umgebungsvariablen –, die die Reproduzierbarkeit von Builds beeinträchtigen können. Für Build-Jobs, die eine saubere Umgebung benötigen, ist der Docker-Executor besser geeignet. Für Deployment-Jobs, die SSH-Befehle auf Zielservern ausführen, ist der Shell-Executor pragmatisch und effizient.

# Shell Executor configuration in /etc/gitlab-runner/config.toml
[[runners]]
  name = "magento-deploy-runner"
  url = "https://gitlab.mironsoft.de/"
  token = "RUNNER_TOKEN"
  executor = "shell"
  shell = "bash"
  [runners.custom_build_dir]
    enabled = true
  [runners.cache]
    Type = "local"
    Shared = false
    [runners.cache.local]
      MaxCacheSize = 10240

# Job using shell executor — SSH access available via system ssh-agent
deploy:production:
  stage: deploy
  tags:
    - magento-deploy-shell    # Target this specific runner
  script:
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | ssh-add -
    - rsync -az ./ "${DEPLOY_USER}@${DEPLOY_HOST}:${RELEASE_PATH}/"
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
      when: manual

3. Docker-Executor: isolierte Container

Der Docker-Executor startet für jeden Job einen neuen Container, führt den Job darin aus und verwirft den Container anschließend. Das garantiert eine saubere, isolierte Umgebung für jeden Job – keine Zustandsakkumulation über Jobs hinweg, keine unerwarteten Abhängigkeiten von vorherigen Ausführungen. Für Build-Jobs, die composer install, npm ci und setup:di:compile ausführen, ist der Docker-Executor die empfohlene Wahl, weil er Reproduzierbarkeit garantiert: Derselbe Job mit demselben Docker-Image erzeugt dasselbe Ergebnis, unabhängig davon, was vorher auf dem Runner-Host passiert ist.

Der Docker-Executor benötigt einen Docker-Daemon auf dem Runner-Host. Die Jobs können beliebige Docker-Images verwenden, die in der .gitlab-ci.yml über das image-Keyword angegeben werden. Für Magento-Build-Jobs bietet sich ein Image wie php:8.4-cli als Basis an, das dann im before_script um notwendige System-Pakete ergänzt wird. Alternativ kann ein vorgefertigtes Magento-Build-Image verwendet werden, das alle benötigten Tools bereits enthält und damit schnellere Build-Starts ermöglicht.

# Docker Executor configuration in /etc/gitlab-runner/config.toml
[[runners]]
  name = "magento-build-runner"
  url = "https://gitlab.mironsoft.de/"
  token = "RUNNER_TOKEN"
  executor = "docker"
  [runners.docker]
    image = "php:8.4-cli"
    pull_policy = ["always", "if-not-present"]
    volumes = ["/cache:/cache"]
    shm_size = 0
    privileged = false  # Never use privileged=true for build jobs

# Build job using Docker executor
build:magento:
  stage: build
  image: php:8.4-cli       # Fresh container for each job
  tags:
    - magento-build-docker
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths:
      - .cache/composer/
      - .cache/npm/
  before_script:
    - apt-get update -qq && apt-get install -y -qq git unzip nodejs npm libzip-dev
    - docker-php-ext-install zip bcmath intl
    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
  script:
    - composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader
    - npm ci --prefix app/design/frontend/Mironsoft/default/web/tailwind
    - npm run build --prefix app/design/frontend/Mironsoft/default/web/tailwind
    - php bin/magento setup:di:compile

4. Kubernetes-Executor: skalierbare Pods

Der Kubernetes-Executor startet für jeden Job einen Kubernetes-Pod, der aus einem oder mehreren Containern besteht. Wenn der Job abgeschlossen ist, wird der Pod automatisch gelöscht. Das bietet die stärkste Isolation aller Executor-Typen und die beste Skalierbarkeit: Kubernetes kann automatisch neue Nodes provisionieren, wenn viele Jobs gleichzeitig ausgeführt werden müssen. Für größere Teams oder Organisationen, die bereits Kubernetes betreiben, ist der Kubernetes-Executor die natürliche Wahl.

Für Magento-Projekte mit überschaubarer Teamgröße und einfacher Infrastruktur ist der Kubernetes-Executor in den meisten Fällen überdimensioniert. Die Einrichtung und Wartung eines Kubernetes-Clusters erfordert erhebliches Infrastruktur-Know-how, und der Overhead für einfache Magento-Deployments ist kaum gerechtfertigt. Wer jedoch bereits Kubernetes betreibt – etwa für andere Anwendungen –, kann den Kubernetes-Executor für Magento-Build-Jobs nutzen und profitiert dabei von automatischer Skalierung, Pod-Isolation und nativer Kubernetes-Integration mit RBAC und Network Policies.

5. Shared Runner: wann sie reichen und wann nicht

GitLab.com bietet Shared Runner, die für alle Nutzer verfügbar sind und keine eigene Runner-Infrastruktur erfordern. Sie verwenden den Docker-Executor mit isolierten Containern und sind für viele Standard-Build-Jobs gut geeignet: Tests ausführen, Code-Qualität prüfen, Abhängigkeiten installieren. Für Magento-Projekte mit öffentlichem Code können Shared Runner für die Build- und Test-Stages ausreichen.

Für Production-Deployments auf eigene Server sind Shared Runner nicht geeignet – aus mehreren Gründen. Erstens haben Shared Runner keinen Zugriff auf interne Netzwerke und können deshalb keine SSH-Verbindungen zu Servern aufbauen, die nicht öffentlich erreichbar sind. Zweitens teilen sich Shared Runner die Infrastruktur mit anderen Nutzern, was Sicherheitsbedenken aufwirft, wenn Production-Secrets in CI/CD-Variablen verwendet werden. Drittens sind Shared Runner weniger vorhersehbar in ihrer Performance und Verfügbarkeit. Für Production-Deployments ist ein selbst gehosteter Runner Pflicht.

6. Runner installieren und registrieren

Die Installation des GitLab Runners erfolgt über das offizielle Package-Repository von GitLab. Für Ubuntu/Debian: apt-get install gitlab-runner nach dem Hinzufügen des GitLab-Repositories. Nach der Installation wird der Runner über gitlab-runner register mit einer GitLab-Instanz verknüpft. Dabei werden die GitLab-Instanz-URL, ein Registration-Token (aus den Projekt- oder Gruppen-Settings), der Name des Runners und der Executor-Typ abgefragt.

Für Magento-Projekte empfiehlt sich eine Zwei-Runner-Strategie: Ein Runner mit Docker-Executor für Build- und Test-Jobs, ein Runner mit Shell-Executor für Deployment-Jobs. Diese Trennung stellt sicher, dass Build-Jobs immer in einer sauberen Container-Umgebung laufen und Deployment-Jobs direkten SSH-Zugriff auf die Deployment-Infrastruktur haben. Beide Runner sollten mit dem Tag-System von GitLab konfiguriert werden, damit Jobs gezielt an den richtigen Runner weitergeleitet werden.

# Runner registration commands
# Install GitLab Runner on Ubuntu 22.04:
# curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
# sudo apt-get install gitlab-runner

# Register Docker Runner for build jobs:
# sudo gitlab-runner register \
#   --url "https://gitlab.mironsoft.de/" \
#   --registration-token "PROJECT_TOKEN" \
#   --description "magento-build-docker" \
#   --tag-list "magento-build,docker,php84" \
#   --executor "docker" \
#   --docker-image "php:8.4-cli"

# Register Shell Runner for deployment jobs:
# sudo gitlab-runner register \
#   --url "https://gitlab.mironsoft.de/" \
#   --registration-token "PROJECT_TOKEN" \
#   --description "magento-deploy-shell" \
#   --tag-list "magento-deploy,shell,production" \
#   --executor "shell"

# Reference runner via tags in .gitlab-ci.yml:
build:magento:
  tags:
    - magento-build          # Routes to Docker runner

deploy:production:
  tags:
    - magento-deploy         # Routes to Shell runner

7. Sicherheitsaspekte bei Runner-Typen

Der Shell-Executor ist der sicherheitskritischste Runner-Typ, weil Jobs direkt auf dem Host-System laufen. Wenn ein böswilliger Job oder kompromittierter Code in eine Pipeline gelangt, hat er vollen Zugriff auf alles, worauf der Runner-Benutzer Zugriff hat – Dateisystem, Netzwerk, andere Jobs, gecachte Secrets. Deshalb sollten Shell-Runner nur für Projekte verwendet werden, deren Pipeline vollständig unter Kontrolle ist – kein direktes Ausführen von ungeprüftem Code aus Merge Requests externer Contributor.

Der Docker-Executor bietet deutlich bessere Isolation, weil Jobs in eigenen Containern laufen. Allerdings sollte privileged: true in der Docker-Executor-Konfiguration niemals aktiviert werden, weil das effektiv Root-Zugriff auf den Host-Kernel gibt und die Container-Isolation aufhebt. Für Shared Runner, auf denen Jobs verschiedener Nutzer laufen, ist der Docker-Executor mit korrekter Konfiguration das Sicherheitsminimum. Für eigene Runner sollten zusätzlich Network Policies, Resource-Limits und regelmäßige Runner-Image-Updates eingerichtet werden.

8. Runner-Typen im direkten Vergleich

Die Wahl des richtigen Runner-Typs ist eine Abwägung zwischen Einfachheit, Isolation und Skalierbarkeit. Für Magento-Projekte typischer Größe gibt es klare Empfehlungen, aber die optimale Konfiguration hängt von der spezifischen Infrastruktur und den Sicherheitsanforderungen ab.

Die optimale Strategie für die meisten Magento-Projekte: ein self-hosted Runner mit Docker-Executor für Build- und Test-Jobs und ein self-hosted Runner mit Shell-Executor für Deployment-Jobs. Diese Kombination liefert reproduzierbare Builds durch Container-Isolation und praktische Deployment-Kontrolle durch direkten Host-Zugriff. Der Overhead für diese Zwei-Runner-Konfiguration ist gering, und die gewonnene Sicherheit und Reproduzierbarkeit ist erheblich.

9. Zusammenfassung

Die Wahl des richtigen GitLab Runner-Typs für Magento-Projekte ist keine technische Nebenfrage, sondern eine Grundsatzentscheidung, die die Reproduzierbarkeit, Sicherheit und Wartbarkeit aller Pipeline-Jobs beeinflusst. Shell-Runner sind einfach und bieten SSH-Zugriff für Deployments, aber keine Isolation für Build-Jobs. Docker-Runner garantieren reproduzierbare Builds durch Container-Isolation, benötigen aber Docker auf dem Host. Kubernetes-Runner bieten maximale Skalierbarkeit, sind aber für kleinere Magento-Projekte überdimensioniert. Shared Runner reichen für einfache Build-Jobs, sind aber für Production-Deployments auf eigene Server nicht geeignet.

Die empfohlene Konfiguration für Magento: Mindestens ein self-hosted Runner mit Docker-Executor für Build- und Test-Jobs und ein self-hosted Runner mit Shell-Executor für Deployment-Jobs. Beide Runner werden über Tags konfiguriert und in der .gitlab-ci.yml gezielt angesprochen. Diese Trennung macht das System wartbarer, sicherer und einfacher zu debuggen – weil Build-Probleme auf dem Docker-Runner und Deployment-Probleme auf dem Shell-Runner klar voneinander getrennt sind.

10. Empfehlung für Magento-Projekte

Basierend auf den Eigenschaften der verschiedenen Runner-Typen ergibt sich für Magento-Projekte eine klare Empfehlung: Für den Build-Runner sollte ein selbst gehosteter Runner mit Docker-Executor auf einem dedizierten Build-Server eingerichtet werden. Der Server benötigt Docker, ausreichend RAM für Composer und npm (mindestens 4 GB), und schnellen Disk-Zugriff für den Composer-Cache. Die Runner-Konfiguration sollte Caching für Composer-Pakete und npm-Module aktivieren, um Build-Zeiten zu reduzieren.

Für den Deploy-Runner empfiehlt sich ein Shell-Executor auf einem Server, der Netzwerkzugriff auf alle Deployment-Ziele hat – idealerweise ein Bastion Host oder Jump Server in derselben Netzwerkzone wie die Web-Server. Der Deployment-User auf dem Runner sollte nur die SSH-Schlüssel enthalten, die für das Deployment notwendig sind, und keine anderen Berechtigungen haben. Der Runner sollte nicht auf einem der Deployment-Zielserver selbst laufen, weil das bei einem fehlgeschlagenen Deployment zu Konflikten führen kann.

11. FAQ: GitLab Runner Typen für Magento