Deployment-Checkliste für Magento-Teams mit GitLab als Standardprozess

1. Warum eine Deployment-Checkliste kein Overhead ist

In vielen Magento-Teams wird eine Deployment-Checkliste als bürokratischer Overhead wahrgenommen — etwas für träge Konzernprozesse, nicht für ein agiles Team. Diese Sichtweise dreht sich meist nach dem ersten nicht dokumentierten Notfall. Eine Checkliste ist kein Zeichen von Misstrauen in das Team, sondern die Externalisierung von implizitem Wissen. Sie macht sichtbar, was alle im Kopf haben, aber nie schriftlich fixiert haben — und genau das zeigt, was fehlt.

Für Magento-Teams mit GitLab ist eine Checkliste besonders wertvoll, weil der Deployment-Prozess viele bewegliche Teile hat: Repository-Regeln, CI/CD-Variablen, Runner-Konfiguration, Build-Artefakte, Release-Struktur, Shared-Pfade, Magento-spezifische Schritte, Verify-Jobs und Rollback-Pfade. Jeder dieser Bereiche hat Voraussetzungen, die erfüllt sein müssen, damit das Deployment funktioniert. Eine Checkliste macht diese Abhängigkeiten explizit und ermöglicht es dem Team, neue Mitglieder schnell einzubinden.

Ein weiterer Nutzen: Eine durchlaufene Checkliste ist Dokumentation nach dem Deployment. Wer später nachvollziehen will, was wann geändert wurde und ob alle Schritte korrekt ausgeführt wurden, hat mit einer Checkliste einen Ausgangspunkt für die Nachanalyse. Das gilt besonders dann, wenn ein Problem erst Stunden oder Tage nach dem Deployment auftritt.

2. Repository-Grundlage: Branches, Tags und Schutzmechanismen

Die erste Checklisten-Kategorie betrifft das Repository selbst. Ohne korrekt eingerichtete Branch-Protection und Tag-Regeln kann jeder Entwickler mit Repository-Zugriff unbeabsichtigt ein Deployment auf Production auslösen. Für Magento-Projekte sind mindestens folgende Einstellungen notwendig: main und alle release/*-Branches als Protected Branches konfiguriert, sodass Pushes nur über Merge Requests möglich sind. Protected Tags mit Muster v*, sodass nur berechtigte Rollen Release-Tags setzen können.

Merge-Request-Einstellungen sollten mindestens einen Reviewer erfordern und den Merge erst nach grüner Pipeline erlauben. Das stellt sicher, dass kein Code auf main landet, der nicht die CI-Prüfung bestanden hat. Environment-Scopes für Variablen müssen so gesetzt sein, dass Staging-Secrets nicht in Production-Jobs verfügbar sind und umgekehrt.

# GitLab repository governance checklist
# Verify these settings before first production deploy

# 1. Protected branches — only MR-based merges allowed
protected_branches:
  - name: main
    push_access_level: no_one
    merge_access_level: maintainer
  - name: "release/*"
    push_access_level: developer
    merge_access_level: maintainer

# 2. Protected tags — only maintainers can create v* tags
protected_tags:
  - name: "v*"
    create_access_level: maintainer

# 3. Merge request requirements
merge_request_settings:
  approvals_required: 1
  pipelines_must_succeed: true
  prevent_secrets: true

3. CI/CD-Variablen: der Konfigurationsvertrag der Pipeline

CI/CD-Variablen sind der Konfigurationsvertrag zwischen dem GitLab-Projekt und den Pipelines. Ohne vollständig und korrekt gesetzte Variablen schlägt jeder Deploy-Job fehl — oder schlimmer, er läuft durch, verwendet aber falsche Werte. Für Magento müssen mindestens SSH-Schlüssel, Zielserver-Adresse, Deploy-Pfad und Composer-Auth-Token vorhanden sein. Jede Variable muss dem richtigen Environment-Scope zugewiesen sein.

Protected-Variables dürfen nur in Pipelines auf Protected Branches oder Tags verfügbar sein. Das verhindert, dass ein Merge-Request von einem Fork die Produktionsgeheimnisse auslesen kann. Masked-Variables verbergen den Wert in Pipeline-Logs, was für SSH-Schlüssel und API-Tokens Pflicht ist. Die Unterscheidung zwischen File-Variables (für mehrzeilige Werte wie SSH-Schlüssel oder env.php-Inhalte) und einfachen String-Variables sollte explizit getroffen werden.

4. Runner-Konfiguration und Sicherheitsvoraussetzungen

Der GitLab-Runner ist das ausführende System der Pipeline und muss entsprechend konfiguriert und gesichert sein. Für Magento-Deployments ist ein eigener, selbst gehosteter Runner fast immer vorzuziehen: Er bietet Kontrolle über die installierten Tools, vermeidet das Teilen von Build-Artefakten mit anderen Projekten und ermöglicht direkten Zugriff auf interne Netzwerkressourcen. Shared Runner von GitLab.com sind für den Build geeignet, sollten aber keinen SSH-Zugang zu Produktionsservern haben.

Die Runner-Tags in der .gitlab-ci.yml stellen sicher, dass Deploy-Jobs nur auf dem dafür vorgesehenen Runner ausgeführt werden. Concurrency-Einstellungen verhindern, dass zwei Deployments gleichzeitig auf denselben Server zugreifen. Die Runner-Shell oder das verwendete Docker-Image muss PHP, Composer, Node.js, rsync und den SSH-Client in kompatiblen Versionen enthalten.

# Runner configuration checklist — config.toml excerpt
# Self-hosted runner for Magento deployments

[[runners]]
  name = "magento-deployer"
  url = "https://gitlab.com/"
  executor = "docker"
  # Limit concurrent deploys — prevents race conditions
  limit = 1

  [runners.docker]
    image = "php:8.4-cli"
    # Mount composer cache for faster builds
    volumes = ["/cache/composer:/root/.composer:rw"]
    # Never use privileged mode for deploy jobs
    privileged = false

# deploy:production job uses this runner via tags
# In .gitlab-ci.yml:
# deploy:production:
#   tags:
#     - magento-deployer

5. Build-Checkliste: Artefakte vor dem Deployment

Die Build-Phase ist die erste und wichtigste Qualitätssicherungsschicht. Hier wird festgestellt, ob der Code überhaupt deploybar ist — bevor ein einziger Byte auf den Produktionsserver übertragen wird. Für Magento umfasst die Build-Checkliste: Composer-Installation ohne Dev-Dependencies (--no-dev), NPM-Installation und Frontend-Build mit Tailwind CSS, DI-Kompilierung (setup:di:compile), PHPStan-Analyse mindestens auf Level 5 und PHPUnit-Tests für kritische Module.

Das Build-Artefakt muss alle benötigten Dateien enthalten: vendor/, generated/, kompilierte Tailwind-CSS-Dateien und alle Static-Content-Assets. Die Artefakt-Größe sollte überwacht werden — ein plötzlich größeres Artefakt kann auf versehentlich inkludierte Dev-Dependencies oder Build-Ausgaben hinweisen, die nicht deployt werden sollten.

6. Servervoraussetzungen: Release-Struktur und Shared-Pfade

Bevor das erste Deployment stattfindet, muss die Verzeichnisstruktur auf dem Zielserver vorbereitet sein. Diese Vorbereitung ist einmalig, aber sie ist Voraussetzung für alle nachfolgenden Deployments. Die Verzeichnisstruktur besteht aus einem releases/-Verzeichnis für die einzelnen Release-Stände, einem shared/-Verzeichnis für persistente Daten und einem current-Symlink, der auf den aktiven Release zeigt.

Im shared/-Verzeichnis müssen alle persistenten Dateien und Verzeichnisse bereits existieren: app/etc/env.php mit der produktiven Datenbankverbindung, pub/media/ mit dem aktuellen Medienstand, var/log/ für Anwendungslogs und var/session/ für Sessions. Diese Inhalte werden nicht mit dem Code deployt, sondern bleiben über alle Releases hinweg erhalten und werden per Symlink eingebunden.

# Server preparation checklist — run once before first deploy
# Execute via SSH on target server

# 1. Create base directory structure
mkdir -p /var/www/magento/{releases,shared}
mkdir -p /var/www/magento/shared/app/etc
mkdir -p /var/www/magento/shared/pub/media
mkdir -p /var/www/magento/shared/var/{log,session,cache}

# 2. Place env.php in shared directory (never in releases)
# scp app/etc/env.php deploy@server:/var/www/magento/shared/app/etc/

# 3. Set correct ownership for web server user
chown -R www-data:www-data /var/www/magento/shared

# 4. Verify Nginx/Apache points to /var/www/magento/current/pub
# document root = /var/www/magento/current/pub

7. Deploy-Phase: Symlink-Wechsel und Magento-Schritte

Die Deploy-Phase ist die kritischste Phase des gesamten Prozesses. Sie beginnt mit dem Übertragen des Build-Artefakts in ein neues Release-Verzeichnis und endet mit dem atomaren Wechsel des current-Symlinks. Zwischen diesen beiden Punkten müssen alle Magento-spezifischen Schritte in der richtigen Reihenfolge ausgeführt werden: Shared-Symlinks setzen, setup:upgrade ausführen (wenn Migrationen vorhanden sind), Static Content deployen falls nicht als Artefakt mitgebracht, Maintenance-Mode nur wenn unvermeidlich, und schließlich Cache flushen.

Der Maintenance-Mode sollte als letztes Mittel betrachtet werden, nicht als Standard-Schritt. Für Deployments ohne Datenbankmigrationen oder mit rückwärtskompatiblen Migrationen (Expand/Contract) ist kein Maintenance-Mode notwendig. Der Symlink-Wechsel selbst ist atomar aus Sicht des Webservers, da er nur einen Symlink-Pointer ändert, nicht den Dateistand.

8. Verify-Checkliste nach dem Deployment

Nach jedem Deployment müssen definierte Verifikationsschritte ausgeführt werden. Diese Schritte sind kein Nice-to-have, sondern Teil des Prozesses — ein Deployment gilt erst dann als abgeschlossen, wenn der Verify-Job grün ist. Die Mindestanforderungen: HTTP-200-Response auf dem Health-Endpoint, HTTP-200 auf der Startseite, kein kritischer Fehler in var/log/exception.log innerhalb der ersten zwei Minuten nach dem Deploy, und Magento-Cache-Status ohne kritische Fehler.

Für Shops mit hohem Traffic lohnen sich zusätzliche Smoke-Tests für die wichtigsten Customer-Journeys: Kategorieseite abrufen, Produktdetailseite laden, Warenkorb-Endpunkt prüfen. Diese Tests können mit einfachen curl-Aufrufen oder einem leichtgewichtigen Test-Framework wie Playwright oder Cypress realisiert werden und direkt als GitLab-CI-Jobs konfiguriert werden.

9. Rollback-Checkliste: Rückweg dokumentieren und üben

Die Rollback-Checkliste ist die am häufigsten vernachlässigte und gleichzeitig die wichtigste. Ein Rollback-Prozess, der nur theoretisch existiert, ist keiner. Er muss dokumentiert, getestet und mindestens einmal auf Staging vollständig durchgeführt worden sein, bevor er im Ernstfall gebraucht wird. Für Magento mit GitLab bedeutet das: ein dedizierter Rollback-Job in der Pipeline, der manuell oder automatisch bei Verify-Fehler ausgelöst werden kann.

Der Rollback-Job schaltet den current-Symlink auf den letzten stabilen Release und flusht den Cache. Er muss die Rollback-Aktion in den Pipeline-Logs protokollieren, damit nachvollziehbar ist, wann und warum zurückgerollt wurde. Nach einem Rollback muss der Verify-Job erneut ausgeführt werden, um zu bestätigen, dass der vorherige Stand tatsächlich wieder funktioniert.

# rollback:production job — manual trigger or auto on verify failure
rollback:production:
  stage: rollback
  image: php:8.4-cli
  when: manual
  environment:
    name: production
    action: stop
  script:
    - apt-get update -qq && apt-get install -y -qq openssh-client
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
    # List available releases and switch to the previous one
    - |
      ssh "$DEPLOY_USER@$DEPLOY_HOST" '
        set -euo pipefail
        PREV=$(ls -1t '"$DEPLOY_PATH"'/releases/ | sed -n "2p")
        if [ -z "$PREV" ]; then echo "[ERROR] No previous release found"; exit 1; fi
        ln -sfn "'"$DEPLOY_PATH"'/releases/$PREV" "'"$DEPLOY_PATH"'/current"
        cd "'"$DEPLOY_PATH"'/current"
        php bin/magento cache:flush
        echo "[OK] Rolled back to: $PREV"
      '
  needs: ["verify:production"]

10. Zusammenfassung

Eine Deployment-Checkliste für Magento-Teams mit GitLab ist kein bürokratisches Dokument, sondern das explizit gemachte implizite Wissen des Teams. Sie umfasst Repository-Governance mit Protected Branches und Tags, vollständig gesetzte CI/CD-Variablen mit korrekten Environment-Scopes, einen konfigurierten und gesicherten Runner, reproduzierbare Build-Artefakte ohne Dev-Dependencies, vorbereitete Release-Struktur mit Shared-Pfaden auf dem Server, eine definierte Deploy-Reihenfolge für Magento-spezifische Schritte, automatisierte Verify-Jobs nach dem Symlink-Wechsel und einen getesteten Rollback-Pfad.

Das Wichtigste ist nicht, dass jeder Punkt auf einmal umgesetzt wird, sondern dass das Team einen gemeinsamen Stand darüber hat, welche Punkte erfüllt sind und welche nicht. Eine ehrliche Lückenanalyse mit dieser Checkliste zeigt, wo der Deployment-Prozess wirklich steht — nicht wo man ihn gerne hätte.

11. FAQ: Deployment-Checkliste für Magento-Teams mit GitLab

Eine lebendige Deployment-Checkliste ist kein bürokratisches Dokument, sondern das Gedächtnis des Teams — sie wächst mit jedem Vorfall und macht wiederkehrende Fehler sichtbar, bevor sie in Production auftreten.