Post-Deploy Checks: Health Endpoint, Smoke Tests, DB-Check, Cache-Check

1. Warum Post-Deploy Checks zur Pipeline gehören

Ein Deployment endet nicht mit dem Symlink-Wechsel oder dem letzten cache:flush-Kommando. Es endet, wenn die Anwendung nachweislich auf Anfragen antwortet, die Datenbank erreichbar ist, der Cache korrekt initialisiert wurde und kritische Pfade wie Login, Checkout und API-Routen funktionieren. Ohne Post-Deploy Checks bleibt die Pipeline bei einer technischen Definition von "erfolgreich" stecken, die nichts über den tatsächlichen Zustand der Anwendung aussagt.

In der Praxis bedeutet das: Ein Deploy kann technisch fehlerfrei durchlaufen und trotzdem eine defekte Anwendung hinterlassen. Eine falsch gesetzte Umgebungsvariable, ein inkompatibler Cache-Eintrag aus dem alten Release, eine fehlgeschlagene Migration, die keinen Exit-Code ungleich 0 zurückgegeben hat – all das bleibt ohne Verify-Stage unsichtbar, bis ein Nutzer oder ein Monitoring-System den Fehler meldet. Post-Deploy Checks schließen diese Lücke, bevor sie zum Problem wird.

Die gute Nachricht: Für Magento-Deployments sind die wichtigsten Checks einfach implementiert. Ein curl -f auf den Health-Endpoint, ein bin/magento cache:status, ein einfacher DB-Verbindungstest über Magento-CLI und ein HTTP-Status-Check auf kritische Seiten – das sind keine komplexen Tests, sondern minimale Überprüfungen mit hohem Erkennungsnutzen. Sie dauern unter 30 Sekunden und gehören in jeden produktiven Deploy-Prozess.

2. Health Endpoint: der erste Lebenszeichen-Check

Der Health Endpoint ist der schnellste und robusteste erste Check nach einem Deployment. Er sollte eine einfache JSON-Antwort mit HTTP-Status 200 zurückgeben und ausdrücklich nicht die Datenbank abfragen oder den Cache befüllen – er prüft nur, ob die PHP-Anwendung erreichbar ist und grundlegend antwortet. In Magento kann ein solches Endpoint über ein simples Controller-Modul implementiert werden, das nichts weiter tut als eine statische JSON-Antwort auszugeben.

Ein Health Endpoint hat einen weiteren Vorteil: Er kann vom Load Balancer, von Monitoring-Systemen und von der GitLab-Pipeline gleichzeitig genutzt werden. Das bedeutet, dass derselbe Endpunkt, der während des Deployments über den Verify-Job überprüft wird, auch im laufenden Betrieb kontinuierlich überwacht werden kann. Ein einmal implementierter Health Endpoint zahlt sich in vielen Kontexten aus.

# Verify stage — post-deploy checks for Magento
verify:production:
  stage: verify
  needs: ["deploy:production"]
  script:
    # Step 1: Health endpoint — basic PHP reachability
    - |
      for i in 1 2 3 4 5; do
        STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://shop.example.com/health)
        if [ "$STATUS" = "200" ]; then
          echo "Health check passed (attempt $i)"
          break
        fi
        echo "Health check failed with status $STATUS — retrying in 5s"
        sleep 5
        [ $i -eq 5 ] && exit 1
      done

    # Step 2: Homepage smoke test
    - curl -f --max-time 15 https://shop.example.com/

    # Step 3: Cache status via Magento CLI
    - |
      ssh "${DEPLOY_USER}@${DEPLOY_HOST}" \
        "cd ${DEPLOY_PATH}/current && php bin/magento cache:status" \
        | grep -v "disabled" || { echo "Cache check failed"; exit 1; }
  when: on_success
  allow_failure: false

3. Smoke Tests: kritische Pfade in Sekunden prüfen

Smoke Tests überprüfen die wichtigsten Seiten und Funktionen der Anwendung auf HTTP-Ebene – ohne sich in die Anwendungslogik einzuloggen oder komplexe Benutzerszenarien zu simulieren. Für einen Magento-Shop bedeutet das: Startseite, Kategorie-Seite, Produkt-Detail-Seite, Warenkorb-Seite und wenn möglich die Login-Seite. Diese fünf Seiten decken die kritischsten Rendering-Pfade ab, ohne dass ein echter Checkout-Prozess simuliert werden muss.

Das zentrale Tool für Smoke Tests in GitLab-Pipelines ist curl mit den Flags -f (Fehler bei nicht-200-Status), --max-time (Timeout) und -L (Weiterleitungen folgen). Diese Kombination erkennt zuverlässig 500-Fehler, Wartungsseiten, fehlerhafte Redirects und Timeout-Probleme – alles typische Symptome eines defekten Deployments. Wer zusätzlich den HTTP-Antwort-Header prüfen will, kann mit curl -I und grep arbeiten.

4. DB-Check: Datenbankverbindung und Migration validieren

Ein DB-Check nach dem Deployment stellt sicher, dass die Datenbankverbindung aus dem neuen Release-Verzeichnis heraus funktioniert und alle Migrationen korrekt durchgeführt wurden. Magento bietet mit bin/magento setup:db:status ein Kommando, das genau das prüft: es meldet, ob ausstehende Migrationen vorhanden sind, die noch nicht ausgeführt wurden. Ein Exit-Code ungleich 0 bedeutet, dass die Datenbank nicht im erwarteten Zustand ist.

Dieser Check ist besonders wichtig, weil setup:upgrade in manchen Fehlerzuständen mit Exit-Code 0 endet, aber die Migration trotzdem nicht vollständig abgeschlossen hat. Das passiert selten, aber wenn es passiert, bleibt die Anwendung in einem inkonsistenten Zustand, bis es manuell erkannt und behoben wird. Ein setup:db:status im Verify-Job fängt diesen Fall ab und blockiert die Pipeline, bevor Nutzer den defekten Zustand erleben.

5. Cache-Check: Magento-Cache-Status nach dem Deploy

Nach einem Magento-Deployment sollte der Cache-Check zwei Dinge bestätigen: dass alle kritischen Cache-Typen aktiviert sind und dass keine ungültig markierten Cache-Einträge auf einen nicht abgeschlossenen Setup-Schritt hinweisen. bin/magento cache:status gibt eine tabellarische Übersicht aller Cache-Typen mit ihrem aktuellen Zustand aus. Ein disabled-Eintrag für config oder layout ist ein Warnsignal.

Darüber hinaus sollte geprüft werden, ob Redis als Cache-Backend erreichbar ist. Ein einfaches redis-cli ping über SSH, das PONG zurückgibt, bestätigt die Verbindung. Wenn Redis nicht antwortet und Magento auf Dateibasiertes Caching zurückfällt, verschlechtert sich die Performance drastisch, ohne dass ein expliziter Fehler sichtbar ist. Dieser Check kostet eine Sekunde und verhindert stille Performance-Degradation nach dem Deployment.

# Extended verify job with DB check and Redis connectivity
verify:extended:
  stage: verify
  needs: ["deploy:production"]
  script:
    # Check Magento DB migration status
    - |
      DB_STATUS=$(ssh "${DEPLOY_USER}@${DEPLOY_HOST}" \
        "cd ${DEPLOY_PATH}/current && php bin/magento setup:db:status 2>&1")
      echo "$DB_STATUS"
      echo "$DB_STATUS" | grep -q "All modules are up to date" \
        || { echo "DB migration check failed"; exit 1; }

    # Check Redis connectivity
    - |
      REDIS_PING=$(ssh "${DEPLOY_USER}@${DEPLOY_HOST}" \
        "redis-cli -h ${REDIS_HOST} ping 2>&1")
      [ "$REDIS_PING" = "PONG" ] \
        || { echo "Redis not reachable: $REDIS_PING"; exit 1; }

    # Check all required cache types are enabled
    - |
      ssh "${DEPLOY_USER}@${DEPLOY_HOST}" \
        "cd ${DEPLOY_PATH}/current && php bin/magento cache:status" \
        | grep "disabled" && { echo "Cache types disabled — check needed"; exit 1; } || true

    # Verify static files are present
    - ssh "${DEPLOY_USER}@${DEPLOY_HOST}" \
        "test -f ${DEPLOY_PATH}/current/pub/static/frontend/Mironsoft/default/de_DE/requirejs-config.js" \
        || { echo "Static files missing"; exit 1; }
  when: on_success

6. Verify-Job in GitLab CI konfigurieren

Der Verify-Job in GitLab CI wird als eigene Stage nach der Deploy-Stage definiert. Das needs-Keyword stellt sicher, dass der Verify-Job erst startet, wenn der Deploy-Job erfolgreich abgeschlossen ist. Mit allow_failure: false wird sichergestellt, dass ein gescheiterter Verify-Job die gesamte Pipeline als fehlgeschlagen markiert – das ist die gewünschte Behavior, denn ein fehlgeschlagener Verify entspricht einem defekten Deployment.

Für Umgebungen mit Warmup-Zeit nach dem Symlink-Wechsel – etwa wenn PHP-FPM-Prozesse noch die alten Opcache-Einträge halten – sollte der Verify-Job eine initiale Verzögerung haben. Das kann über ein einfaches sleep 10 vor den ersten Checks erreicht werden. Alternativ implementiert man eine Retry-Schleife, die bis zu fünfmal versucht und bei Erfolg abbricht – das ist robuster als ein fester Sleep.

7. Was bei einem fehlgeschlagenen Check passieren soll

Ein gescheiterter Post-Deploy Check ist kein Fehler, der ignoriert werden darf – er ist das Signal, dass das Deployment in einem defekten Zustand geendet hat. Die Reaktion muss klar definiert sein, bevor der erste Fehler auftritt. Die drei häufigsten Reaktionsmuster: sofortiger manueller Rollback über die GitLab-Pipeline, automatischer Rollback über eine on_failure-Stage und sofortige Alert-Benachrichtigung an Slack oder E-Mail, während der Rollback manuell entschieden wird.

Das automatische Rollback-Muster klingt attraktiv, hat aber eine wichtige Einschränkung: Wenn der Verify-Job nach einer erfolgreichen DB-Migration fehlschlägt und ein automatischer Rollback ausgeführt wird, zeigt der Code-Stand wieder auf das alte Release, aber die Datenbankstruktur entspricht der neuen Version. Das kann in einen inkonsistenten Zustand führen. Für Deployments mit Datenbankmigrationen ist ein manuell genehmigter Rollback daher oft die sicherere Wahl.

8. Timeouts und Retry-Logik in Verify-Jobs

Verify-Jobs müssen mit Timeouts und Retry-Logik ausgestattet werden, weil Produktionssysteme nach einem Deployment keine sofortige Vollverfügbarkeit garantieren. PHP-FPM-Pools können kurz überlastet sein, der erste Request nach einem Opcache-Clear dauert länger als übliche Requests, und der Cache muss erst befüllt werden, bevor er das Antwortverhalten normalisiert. Ein Verify-Job, der beim ersten Timeout sofort scheitert, produziert falsche Negative.

Die empfohlene Strategie: eine Schleife mit maximal fünf Versuchen, einer Wartezeit von fünf Sekunden zwischen den Versuchen und einem expliziten Exit-Code 1 nach dem letzten fehlgeschlagenen Versuch. Das gibt der Anwendung bis zu 25 Sekunden Zeit, sich zu stabilisieren, ohne den Verify-Job in einen dauerhaften Hänger zu verwandeln. Mit timeout: 3 minutes auf Job-Ebene gibt es zusätzlich eine harte Obergrenze.

# Smoke test job with proper retry logic and timeouts
verify:smoke:
  stage: verify
  timeout: 3 minutes
  script:
    # Allow application to stabilize after symlink switch
    - sleep 10

    # Retry loop for homepage check
    - |
      for attempt in 1 2 3 4 5; do
        HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
          --max-time 10 --connect-timeout 5 \
          https://shop.example.com/)
        if [ "$HTTP_CODE" = "200" ]; then
          echo "Homepage OK (attempt $attempt)"
          break
        fi
        echo "Attempt $attempt failed — HTTP $HTTP_CODE"
        [ $attempt -lt 5 ] && sleep 5 || exit 1
      done

    # Category page check
    - curl -f --max-time 15 https://shop.example.com/category-name/

    # Product detail page
    - curl -f --max-time 15 https://shop.example.com/product-url.html

    # Admin login check — should return 200, not 302 to maintenance
    - |
      ADMIN_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
        https://shop.example.com/admin/)
      [ "$ADMIN_CODE" = "200" ] || [ "$ADMIN_CODE" = "302" ] \
        || { echo "Admin unreachable — HTTP $ADMIN_CODE"; exit 1; }
  when: on_success

9. Check-Methoden im Vergleich

Nicht alle Post-Deploy Checks sind gleich wertvoll. Die folgende Tabelle zeigt die häufigsten Methoden, ihre Erkennungstiefe und ihre typische Ausführungszeit im Verify-Job.

Die Kombination aus Health Endpoint, Homepage-Smoke-Test und cache:status ist der Minimalstandard, der nach jedem Magento-Deployment ausgeführt werden sollte. Der DB-Check und Redis-Check kommen bei Releases hinzu, die Datenbankmigrationen oder Cache-Konfigurationsänderungen enthalten. Diese Differenzierung erlaubt schnelle Verify-Jobs bei kleinen Releases und gründlichere Checks bei größeren Deployments.

10. Zusammenfassung

Post-Deploy Checks sind der Unterschied zwischen einer Pipeline, die technisch endet, und einer Pipeline, die fachlich abschließt. Health Endpoint, Smoke Tests, DB-Check und Cache-Check decken zusammen die wichtigsten Fehlerklassen nach einem Magento-Deployment ab: PHP nicht erreichbar, Rendering defekt, Migration unvollständig, Cache-Typen deaktiviert, Redis nicht erreichbar. Diese Checks laufen in unter 30 Sekunden und erfordern keine externen Test-Frameworks.

Das Wichtigste ist nicht die perfekte Test-Abdeckung, sondern die konsequente Ausführung nach jedem Deployment. Ein einfacher Health-Check und ein Homepage-Smoke-Test, die bei jedem Release ausgeführt werden, haben mehr Wert als eine umfangreiche Test-Suite, die aus Zeitgründen gelegentlich übersprungen wird. Automatisierung schlägt Vollständigkeit, wenn es um Post-Deploy Checks geht.

11. FAQ: Post-Deploy Checks für Magento