Manuelle Notfall-Deployments dokumentieren und absichern

1. Wann ein manuelles Deployment legitim ist

Ein manuelles Notfall-Deployment ist keine Niederlage gegen den Automatisierungsprozess, sondern ein bewusstes Ausnahmeventil für Situationen, in denen der reguläre Pipeline-Durchlauf zu langsam wäre. Wenn ein kritischer Bug im Liveshop zu Umsatzverlust führt – ein defekter Checkout, eine kaputte Zahlungsintegration, eine fehlerhafte Preisberechnung –, dann zählt jede Minute. Eine normale Pipeline mit Build, Tests und manueller Freigabe kann fünfzehn Minuten dauern. Das manuelle Deployment kann in drei Minuten abgeschlossen sein.

Das Problem ist nicht das manuelle Deployment selbst, sondern der Weg, wie es üblicherweise durchgeführt wird: ohne Protokoll, ohne Rollback-Vorbereitung, ohne Dokumentation im GitLab-Issue. Wer hinterher wissen will, wer wann was auf welchem Server geändert hat, findet oft nur Lücken im Audit-Log. Genau diese Lücken gilt es zu schließen – nicht durch das Verbot manueller Deployments, sondern durch einen klar definierten Prozess für den Ausnahmefall.

2. Die Risiken unkontrollierter Notfall-Deployments

Das größte Risiko eines improvisierten Notfall-Deployments ist der Verlust der Reproduzierbarkeit. Wenn ein Entwickler unter Zeitdruck direkt auf dem Server Dateien ändert, entsteht ein Zustand, der nirgendwo im Repository abgebildet ist. Der nächste reguläre Deploy über die Pipeline überschreibt diese Änderungen, ohne dass irgendjemand davon weiß. Oder noch schlimmer: der Hotfix ist im Git-Repository, aber der reguläre Deploy-Prozess läuft gegen eine Datenbankstruktur, die der Hotfix bereits geändert hat.

Ein weiteres Risiko ist die fehlende Abgrenzung des Notfall-Deployments. Unter Druck neigen Entwickler dazu, mehr zu ändern als nötig. Was als Einzeldatei-Hotfix beginnt, endet mit fünf geänderten Dateien, einer neuen Konfiguration und einem cache:flush, der andere Probleme verbirgt. Dokumentation zwingt zur Eingrenzung: was genau wird geändert, warum und mit welcher Erwartung? Diese Fragen bremsen nicht – sie verhindern, dass der Notfall-Deploy selbst zum Problem wird.

3. Vorbereitung: was vor dem Notfall bereitstehen muss

Die beste Vorbereitung für Notfall-Deployments ist eine vollständige Release-Struktur, die Rollback in Sekunden ermöglicht. Das bedeutet: auf dem Produktionsserver liegen mindestens die letzten fünf Releases als vollständige Verzeichnisse, ein Symlink current zeigt auf den aktiven Stand, und ein vorbereitetes Rollback-Skript kann ohne Recherche ausgeführt werden. Wenn diese Struktur im Normalbetrieb gepflegt wird, ist sie im Notfall sofort verfügbar.

Ebenso wichtig ist ein vorbereitetes Notfall-Bash-Skript, das die häufigsten Hotfix-Szenarien abdeckt: Einzeldatei ersetzen, Cache leeren, einen einzelnen Patch einspielen. Dieses Skript sollte mit vollständiger Protokollierung ausgestattet sein – jede Aktion wird mit Zeitstempel, ausführendem Benutzer und Hostname in eine Logdatei geschrieben. Das Skript liegt im Repository und wird regelmäßig geprobt, nicht erst im Notfall zum ersten Mal ausgeführt.

# .gitlab-ci.yml — emergency hotfix pipeline (fast path)
hotfix:deploy:
  stage: deploy
  environment:
    name: production
    url: https://shop.example.com
  variables:
    GIT_STRATEGY: fetch
  script:
    # Document who triggered this emergency deploy
    - echo "EMERGENCY DEPLOY by ${GITLAB_USER_LOGIN} at $(date -u)"
    - echo "Triggered from pipeline ${CI_PIPELINE_ID}, commit ${CI_COMMIT_SHA}"
    # Transfer only changed files (faster than full rsync)
    - |
      ssh "${DEPLOY_USER}@${DEPLOY_HOST}" "
        set -euo pipefail
        HOTFIX_LOG=${DEPLOY_PATH}/shared/var/log/hotfix-$(date +%Y%m%d-%H%M%S).log
        echo 'HOTFIX START: $(date -u)' >> \$HOTFIX_LOG
        echo 'User: ${GITLAB_USER_LOGIN}' >> \$HOTFIX_LOG
        echo 'Commit: ${CI_COMMIT_SHA}' >> \$HOTFIX_LOG
        echo 'Pipeline: ${CI_PIPELINE_ID}' >> \$HOTFIX_LOG
        cd ${DEPLOY_PATH}/current &&
        bin/magento cache:flush &&
        echo 'HOTFIX END: $(date -u)' >> \$HOTFIX_LOG"
  when: manual
  allow_failure: false
  rules:
    - if: '$CI_COMMIT_BRANCH == "hotfix/*"'
      when: manual

4. Protokollierung während des Deployments

Jede Aktion in einem Notfall-Deployment muss protokolliert werden. Das Mindestformat: Zeitstempel in UTC, Benutzername, ausgeführter Befehl, Ergebnis (Erfolg oder Fehler mit Exit-Code). In Bash erreicht man das mit einer Wrapper-Funktion, die jeden Befehl erst ins Log schreibt, dann ausführt und das Ergebnis ebenfalls protokolliert. Diese Funktion kostet fünfzehn Zeilen Code und spart im Störfall Stunden Debugging.

Die Logdatei sollte an einem Ort landen, der von regulären Deployments nicht überschrieben wird – also im shared/var/log/-Verzeichnis, nicht im Release-Verzeichnis. Wer einen Root-Cause-Analysis-Prozess nach Störfällen etablieren will, braucht diese Logs. Ohne sie ist jede Post-mortem-Analyse eine Rekonstruktion aus Erinnerungen – unzuverlässig und im Zweifel schuldzuweisend statt lösungsorientiert.

5. GitLab als Audit-Trail für manuelle Aktionen

GitLab bietet mehrere Mechanismen, um manuelle Aktionen im Deployment-Kontext sichtbar zu machen. Der erste ist der Pipeline-Audit-Trail: jede manuell getriggerte Pipeline hat einen Eintrag, wer sie ausgelöst hat, wann und aus welchem Branch. Dieser Trail ist unveränderlich und kann nicht im Nachhinein editiert werden. Für Compliance-Anforderungen in E-Commerce-Projekten ist das ein wertvoller Nachweis.

Der zweite Mechanismus sind GitLab-Environment-Jobs. Wenn ein Hotfix als manueller Job in der Pipeline modelliert ist, erscheint er im Deployment-Tab des Environments mit Zeitstempel, Pipeline-ID und ausführendem Benutzer. Das macht auch außerordentliche Deployments für das gesamte Team transparent und verhindert, dass der nächste reguläre Deploy einen undokumentierten Zustand vorfindet. Als dritten Mechanismus sollte der Hotfix-Commit mit einer aussagekräftigen Commit-Message versehen werden, die das Ticket-Nummer des Incidents und eine kurze Beschreibung enthält.

# Dedicated verify job after every emergency deploy
verify:hotfix:
  stage: verify
  script:
    # Confirm no stale maintenance flag remains
    - |
      ssh "${DEPLOY_USER}@${DEPLOY_HOST}" "
        test ! -f ${DEPLOY_PATH}/current/var/.maintenance.flag"
    # HTTP check on critical paths
    - curl --fail --silent --max-time 10
        https://shop.example.com/
    - curl --fail --silent --max-time 10
        https://shop.example.com/checkout/cart/
    # Log verification result to shared audit log
    - |
      ssh "${DEPLOY_USER}@${DEPLOY_HOST}" "
        echo 'VERIFY OK: $(date -u) | Pipeline ${CI_PIPELINE_ID}' >>
          ${DEPLOY_PATH}/shared/var/log/hotfix-audit.log"
  needs: ["hotfix:deploy"]
  rules:
    - if: '$CI_COMMIT_BRANCH == "hotfix/*"'

6. Hotfix-Pipeline: schnell und trotzdem kontrolliert

Die beste Lösung für Notfall-Deployments ist keine vollständige Ausschaltung des Pipeline-Prozesses, sondern eine abgespeckte Hotfix-Pipeline, die die wichtigsten Sicherheitsschritte beibehält, aber auf zeitintensive Schritte verzichtet. Diese Pipeline läuft in unter fünf Minuten: kein vollständiger Build, keine Unit-Tests, aber ein PHPCS-Check auf geänderte Dateien, ein rsync der geänderten Dateien auf den Server, ein Cache-Flush und ein HTTP-Verify. Das ist schnell genug für Notfälle und sicher genug für Produktivumgebungen.

Der kritische Unterschied zur echten Improvisation: die Hotfix-Pipeline ist vorab im Repository definiert, nicht im Notfall zusammengeklickt. Sie wird auf einem dedizierten hotfix/*-Branch ausgelöst, der automatisch auf dem Production-Environment deployt. Das Team muss im Notfall nur einen Branch anlegen, den Fix committen und die manuelle Freigabe in der Pipeline bestätigen. Das dauert drei Minuten – mit vollständigem Audit-Trail.

7. Rollback nach einem Notfall-Deployment

Ein Notfall-Deployment, das selbst zum Problem wird, muss sofort zurückgedreht werden können. In einer sauberen Release-Struktur ist das Rollback eine einzige Operation: den Symlink current auf das vorherige Release-Verzeichnis zeigen lassen. Für Hotfixes, die direkt auf den aktuellen Release-Stand aufgebaut haben, ohne ein neues Release-Verzeichnis zu erstellen, ist der Rollback komplizierter. Das ist ein weiteres Argument für die Hotfix-Pipeline statt direkter Servereingriffe.

Der Rollback nach einem Notfall-Deployment muss ebenfalls dokumentiert werden – mit demselben Protokollformat wie das ursprüngliche Deployment. Wer rollbackt, warum, auf welchen Stand und mit welchem Ergebnis. Diese Information ist Pflichtbestandteil der Post-mortem-Analyse. Ohne sie fehlt dem Team die Grundlage, um zu entscheiden, ob der Rollback vollständig oder nur partiell war und ob der ursprüngliche Fehler noch im System vorhanden ist.

8. Improvisiert vs. dokumentiert im Vergleich

Der Unterschied zwischen einem unkontrollierten und einem dokumentierten Notfall-Deployment zeigt sich oft erst Tage später – beim nächsten regulären Deployment oder beim nächsten Incident. Wer vorher die Standards definiert, zahlt nichts drauf.

9. Rückführung in den Normalprozess

Ein Notfall-Deployment ist immer nur ein Zwischenzustand. Sobald der Incident behoben ist, muss der Hotfix in den normalen Entwicklungsprozess eingeflossen sein: als Commit auf dem Hauptbranch, mit Ticket-Referenz, Code-Review und regulärem Deployment über die vollständige Pipeline. Solange der Hotfix nur auf dem Server liegt und nicht im Repository abgebildet ist, besteht die Gefahr, dass er beim nächsten regulären Deploy überschrieben wird.

Die Nachbereitung umfasst außerdem eine kurze Post-mortem-Analyse: Was hat den Incident verursacht? Warum wurde der Fehler nicht in Staging gefunden? Welche Tests oder Checks hätten ihn abgefangen? Die Antworten auf diese Fragen fließen in bessere Tests, klarere Deployment-Checklisten und robustere Pipeline-Schritte ein. Das ist der eigentliche Gewinn aus einem Notfall-Deployment: die systematische Verbesserung des Prozesses, der ihn verhindern soll.

10. Zusammenfassung

Manuelle Notfall-Deployments sind ein akzeptabler Ausnahmefall im Magento-Betrieb – aber nur mit vollständiger Dokumentation, vorbereitetem Rollback-Pfad und anschließender Rückführung in den Normalprozess. Ein Notfall-Deployment ohne Protokoll ist ein technisches Schuld-Akkumulationsereignis: der Shop läuft, aber der Prozess ist beschädigt. Die Lösung ist keine bürokratische Zusatzlast, sondern eine vorbereitete Hotfix-Pipeline, die in drei Minuten durchläuft und trotzdem alle relevanten Informationen dokumentiert.

Der Schlüssel liegt in der Vorbereitung: Release-Struktur für sofortigen Rollback, vorbereitetes Bash-Protokollskript, definierter Hotfix-Branch-Prozess in GitLab und eine klare Erwartung, was nach dem Notfall-Deploy als Nachbereitung erwartet wird. Wer diese Strukturen im Normalbetrieb aufbaut, zahlt im Störfall einen Bruchteil des Preises, den ein unkontrollierter Notfall-Deploy kostet.

11. FAQ: Manuelle Notfall-Deployments

Manuelle Notfall-Deployments sind kein Zeichen von Schwäche im Prozess — sie sind eine bewusste Sicherheitsoption. Wer sie sauber dokumentiert und absichert, behält die Kontrolle auch dann, wenn die reguläre Pipeline nicht greift.

Der entscheidende Unterschied zwischen Chaos und kontrolliertem Eingriff liegt nicht in der Technik, sondern im Playbook: klare Schritte, klare Verantwortlichkeiten, klare Dokumentation des Ergebnisses.