Git-basierte Deployment-Strategie für Magento-Shops

1. Warum Git die einzige Quelle der Wahrheit für Deployments sein muss

In vielen Magento-Projekten beginnt die Deployment-Realität als reine Improvisation. Ein Entwickler kopiert per FTP oder rsync geänderte Dateien direkt vom eigenen Rechner auf den Produktivserver, oft unter Zeitdruck und ohne nachvollziehbare Dokumentation darüber, welche Version tatsächlich live ist. Git existiert in solchen Setups zwar als Backup-Werkzeug, aber nicht als verbindliche Quelle der Wahrheit für den produktiven Code. Genau das ist der grundlegende Fehler: Sobald FTP-Uploads oder manuelle Dateisynchronisation der offizielle Weg auf den Server sind, gibt es keine verlässliche Antwort mehr auf die Frage, welcher Commit gerade tatsächlich ausgeliefert ist.

Git als Single Source of Truth zu behandeln bedeutet, dass jeder Deployment-Vorgang exakt einen Git-Referenzpunkt, einen Commit-Hash oder ein Tag, als Eingabe hat und niemals den lokalen Dateisystemzustand eines Entwicklerrechners. Das klingt zunächst wie eine formale Feinheit, ist aber der entscheidende Hebel für Reproduzierbarkeit: Wird derselbe Tag zweimal deployed, egal auf welcher Maschine oder von welchem CI-Runner aus, entsteht exakt derselbe Artefakt-Zustand. Dieser Determinismus im Deployment-Prozess lässt sich mit FTP-basierten Workflows praktisch nicht erreichen, weil dort immer der unsichtbare, nicht versionierte Zustand einer lokalen Festplatte mit in den Prozess einfließt.

2. Tag-basierte Release-Strategie: Annotierte Git-Tags als Produktionswahrheit

Ein Branch ist ein beweglicher Zeiger. main oder develop zeigt heute auf einen anderen Commit als vor einer Stunde, sobald jemand pusht. Für Produktionsdeployments ist genau diese Beweglichkeit das Problem: Wenn Produktion "den aktuellen Stand von main" deployed, ist nicht mehr eindeutig rekonstruierbar, welcher Commit zu einem bestimmten Zeitpunkt tatsächlich live war, insbesondere wenn zwischen zwei Deployments mehrere Merges auf main gelandet sind. Ein annotiertes Git-Tag wie v2.4.1 löst dieses Problem, weil es, anders als ein Branch, nicht bewegt werden soll. Ein Tag markiert exakt einen Commit, dauerhaft, mit Tagger, Zeitstempel und Nachricht als eigenes Git-Objekt.

Die Namenskonvention folgt semantischer Versionierung: MAJOR.MINOR.PATCH, wobei MAJOR inkompatible Änderungen, MINOR neue, rückwärtskompatible Funktionalität und PATCH Bugfixes signalisiert. Für ein Magento-Projekt bedeutet das etwa v2.5.0 für ein neues Checkout-Feature und v2.5.1 für einen darauffolgenden Hotfix. Entscheidend ist die Regel, dass ein einmal gepushter Tag niemals verschoben oder überschrieben wird, git tag -f ist in produktiven Workflows tabu. Nur so bleibt die Garantie erhalten, dass v2.4.1 heute exakt denselben Code referenziert wie in sechs Monaten, und dass jede Zeile im Deployment-Log eindeutig einem unveränderlichen Codestand zuzuordnen ist.

# Create an annotated tag following semantic versioning (MAJOR.MINOR.PATCH)
$ git tag -a v2.5.0 -m "Release 2.5.0: new checkout step, cart API fixes"

# Push the tag explicitly, tags are not pushed by a plain "git push"
$ git push origin v2.5.0

# Optional: sign the tag with GPG for a verifiable release trail
$ git tag -s v2.5.1 -m "Hotfix: fix price rounding in cart totals"

# List existing tags sorted by semantic version, newest first
$ git tag --list "v*" --sort=-v:refname

# Inspect what an annotated tag actually is: a full Git object
$ git cat-file -p v2.5.0
object 9f2a1c4b8e7d3f5a6b9c0d1e2f3a4b5c6d7e8f90
type commit
tag v2.5.0
tagger Jane Deploy <jane@mironsoft.de> 1752313200 +0200

Release 2.5.0: new checkout step, cart API fixes

# Never move a tag once it has been pushed, -f is forbidden in production
$ git tag -d v2.5.0 && git tag -a v2.5.0 -m "..."  # do not do this after push

3. Deploy-from-Branch-Pipelines: CI/CD-Trigger auf Branches und Tag-Patterns

CI/CD-Pipelines abonnieren in der Regel zwei Arten von Git-Events: Push-Events auf bestimmte Branches und Push-Events auf Tags, die einem definierten Muster entsprechen. GitHub Actions und GitLab CI erlauben es, im on:-Block beziehungsweise unter rules:, exakt zu deklarieren, welcher Job bei welchem Ereignis läuft, etwa on.push.branches: [main, develop] für Staging und on.push.tags: ["v*.*.*"] für Produktion. Der entscheidende Effekt: Niemand drückt manuell einen Deploy-Button und entscheidet situativ, was gerade released wird. Stattdessen ist das Deployment eine deterministische Funktion eines Git-Ereignisses, vollständig im Pipeline-Code dokumentiert und im Versionskontrollsystem selbst nachvollziehbar.

Innerhalb der Pipeline folgen die Jobs typischerweise denselben Stufen: Build (Composer- und Node-Abhängigkeiten installieren, Assets kompilieren), Test (PHPStan, PHPCS, PHPUnit), Package (ein versioniertes Artefakt oder Docker-Image mit dem Git-Tag als Image-Tag erzeugen) und Deploy (Artefakt auf die Zielumgebung übertragen und dort die Magento-CLI-Befehle ausführen). Für den Produktions-Job lohnt sich zusätzlich ein Environment-Protection-Gate, etwa eine manuelle Freigabe durch einen zweiten Reviewer, bevor der Tag-getriggerte Job tatsächlich gegen die Live-Umgebung läuft, ohne dass dabei der deklarative, ereignisgesteuerte Charakter der Pipeline verloren geht.

name: Deploy Magento Store

on:
  push:
    branches: [main, develop]      # any merge triggers a staging deploy
    tags: ["v*.*.*"]               # only semver tags trigger production

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - name: Deploy branch head to staging
        run: ./deploy.sh staging "${{ github.sha }}"

  deploy-production:
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    environment: production          # requires manual approval gate
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.ref }}
      - name: Deploy immutable tag to production
        run: ./deploy.sh production "${{ github.ref_name }}"

4. Warum das Deployment vom lokalen Checkout riskant ist

Ein Deployment direkt vom lokalen Checkout eines Entwicklers umgeht jede Kontrollinstanz, die eine Pipeline sonst erzwingt. Uncommittete lokale Änderungen, ein schnell getesteter Fix, der nie in einen Commit floss, landen so unbemerkt in Produktion, ohne dass irgendjemand außer dem Entwickler selbst diesen Code je gesehen hat. Genauso kritisch sind Build-Artefakte, die bewusst über .gitignore aus dem Repository ausgeschlossen sind, kompiliertes Tailwind-CSS, gebündeltes JavaScript oder der vendor/-Ordner. Diese Dateien existieren nur lokal in genau der Version, in der sie auf diesem einen Rechner zuletzt gebaut wurden, und können auf dem Produktivserver in einem völlig anderen, undokumentierten Zustand landen.

Hinzu kommt das Problem inkonsistenter Toolchain-Versionen: Läuft auf dem Rechner von Entwickler A PHP 8.4 mit Composer 2.7, auf dem von Entwickler B aber PHP 8.3 mit einer älteren Composer-Version, erzeugen beide unterschiedliche, potenziell inkompatible vendor/-Bäume für dasselbe composer.lock. Und schließlich fehlt der Audit-Trail vollständig: Wer hat wann von welchem Rechner aus welchen Code deployed? Ohne CI/CD-Log gibt es auf diese Fragen im Ernstfall, etwa nach einem produktiven Incident, keine verlässliche Antwort, was Root-Cause-Analysen erheblich erschwert.

5. Branch-zu-Umgebung-Mapping für ein Magento-Projekt

Ein praxistaugliches Mapping für ein Magento-Projekt sieht in der Regel so aus: Jeder Merge nach main oder develop löst automatisch ein Deployment auf die Staging-Umgebung aus, ohne manuelle Freigabe, weil Staging als integrativer, sich ständig bewegender Zustand verstanden wird. Ausschließlich Git-Tags, die dem Muster v[0-9]+.[0-9]+.[0-9]+ entsprechen, lösen ein Deployment auf Produktion aus, üblicherweise zusätzlich abgesichert durch ein manuelles Approval-Gate. Feature-Branches wiederum deployen in ephemere Review- oder Integrationsumgebungen, die pro Branch dynamisch erzeugt und nach dem Merge oder nach Ablauf einer Frist automatisch wieder abgebaut werden.

Dieses Mapping trennt drei unterschiedliche Vertrauensstufen sauber voneinander. Staging zeigt jederzeit den aktuellen Integrationsstand und eignet sich für QA und Stakeholder-Reviews, ist aber bewusst volatil, ein neuer Merge kann jederzeit den dort sichtbaren Stand verändern. Produktion bleibt davon komplett entkoppelt und bewegt sich ausschließlich in expliziten, bewusst gesetzten Schritten, jeder neue Tag ist eine bewusste Entscheidung, kein automatischer Nebeneffekt eines Merges. Diese Trennung verhindert, dass ein versehentlich verfrühter Merge in main automatisch zu einem Produktionsdeployment führt.

; deploy-mapping.ini: branch/tag to environment mapping for the CI/CD runner
[environment.staging]
trigger        = branch
refs           = main, develop
auto_deploy    = true
approval       = none
magento_mode   = developer

[environment.production]
trigger        = tag
ref_pattern    = v[0-9]+.[0-9]+.[0-9]+
auto_deploy    = true
approval       = required, min_reviewers=1
magento_mode   = production

[environment.review]
trigger        = branch
refs           = feature/*
auto_deploy    = true
approval       = none
ttl_hours      = 72
magento_mode   = developer

6. Feature-Branches und ephemere Review-Umgebungen

Ephemere Review-Umgebungen lösen ein Problem, das reine Staging-Umgebungen nicht abdecken können: Wenn mehrere Feature-Branches parallel entwickelt werden, konkurrieren sie auf einer einzigen Staging-Instanz um denselben Zustand und überschreiben sich gegenseitig. Eine dedizierte, pro Branch automatisch erzeugte Umgebung, oft ein eigener Container-Stack mit eigener Subdomain wie feature-1234.review.mironsoft.de, löst dieses Problem, indem jeder Branch seinen eigenen, isolierten Magento-Stack inklusive eigener Datenbank erhält. Reviewer, Product Owner oder QA können die tatsächliche Funktionalität live anklicken, bevor überhaupt über einen Merge nach develop entschieden wird.

Entscheidend für die Praxistauglichkeit ist konsequente Automatisierung beim Abbau: Sobald ein Feature-Branch gemerged oder gelöscht wird, oder eine definierte Time-to-Live überschritten ist, muss die zugehörige Umgebung automatisch wieder verschwinden, sonst sammeln sich verwaiste, nie aktualisierte Hosts an, die selbst zum Sicherheitsrisiko werden. Genauso wichtig: Die Konfiguration dieser Umgebungen, Docker-Compose-Definitionen oder Kubernetes-Manifeste, gehört selbst ins Git-Repository und nicht in eine manuell gepflegte Server-Liste. Nur so bleibt auch die Infrastruktur, nicht nur der Anwendungscode, durch Git versioniert und reproduzierbar.

7. Magento-spezifische Deployment-Schritte in der CI/CD-Pipeline

Innerhalb eines Deployment-Jobs müssen die Magento-CLI-Befehle in einer festen Reihenfolge laufen, weil jeder Schritt auf dem Ergebnis des vorherigen aufbaut. Zuerst composer install --no-dev --optimize-autoloader, um exakt die in composer.lock fixierten Produktionsabhängigkeiten zu installieren, ohne Dev-Pakete. Danach bin/magento setup:upgrade, das Datenbankschema und Datenpatches anwendet, gefolgt von setup:di:compile, das die generierte Dependency-Injection-Konfiguration für den Produktionsmodus baut, ein Schritt, der zwingend nach dem Composer-Install laufen muss, weil er den frisch installierten Code voraussetzt. Erst danach kann setup:static-content:deploy die Frontend-Assets für Hyvä und alle konfigurierten Stores bauen.

Den Abschluss bildet cache:flush, damit keine veralteten Cache-Einträge aus dem vorherigen Deployment bestehen bleiben. Sinnvoll ist außerdem, den gesamten Deployment-Block in maintenance:enable und maintenance:disable einzurahmen, damit Kunden während des kurzen Zeitfensters, in dem Schema-Änderungen laufen, keine inkonsistenten Zwischenzustände sehen. Wichtig ist, all das in exakt derselben PHP-Version und Composer-Version auszuführen wie die Zielumgebung, idealerweise im selben Docker-Image, das später auch produktiv läuft, statt die Schritte manuell auf einem Entwicklerrechner mit abweichender Toolchain vorzubereiten.

#!/usr/bin/env bash
# deploy.sh: Magento deployment steps run inside the CI/CD job,
# executed against the exact PHP/Composer version used in production
set -euo pipefail

TARGET_REF="$1"          # e.g. v2.5.0 (a Git tag) or a branch name
ENVIRONMENT="$2"         # staging | production | review

echo "Deploying ${TARGET_REF} to ${ENVIRONMENT}"
git checkout "${TARGET_REF}"

bin/magento maintenance:enable

composer install --no-dev --optimize-autoloader --no-interaction

bin/magento setup:upgrade --keep-generated
bin/magento setup:di:compile
bin/magento setup:static-content:deploy de_DE en_US -f
bin/magento cache:flush

bin/magento maintenance:disable

echo "Deployment of ${TARGET_REF} to ${ENVIRONMENT} finished successfully"

8. Rollback-Strategie: Redeploy statt Revert unter Zeitdruck

Weil Produktion ausschließlich über unveränderliche Tags deployed wird, reduziert sich ein Rollback auf eine einzige, klar definierte Operation: den zuletzt bekannten guten Tag erneut deployen, nicht neue Commits schreiben. Das ist der entscheidende Unterschied zu einem Team, das Produktion direkt von main betreibt: Dort bedeutet ein Rollback im Ernstfall oft hektisches git revert mitten im Incident, unter Zeitdruck neu geschriebene Commits, die selbst erst durch die komplette Pipeline laufen müssen, inklusive Tests und Compile-Schritten, bevor sie überhaupt live gehen können. Ein Redeploy eines bereits getesteten, bereits einmal erfolgreich produktiv gelaufenen Tags braucht dagegen keine neue Code-Änderung, nur eine erneute Ausführung eines bekannten, deterministischen Prozesses.

In der Praxis lohnt sich ein dediziertes Rollback-Skript, das den vorherigen Produktions-Tag aus der Deployment-Historie liest und denselben Deploy-Job erneut anstößt, statt den Rollback manuell zu improvisieren. Eine Einschränkung bleibt: Datenbank-Migrationen sind nicht automatisch rückwärtskompatibel, ein setup:upgrade, das neue Spalten oder Tabellen anlegt, lässt sich nicht einfach durch Redeploy eines älteren Tags rückgängig machen. Deshalb gehört zur Rollback-Strategie zwingend die Disziplin, Schema-Änderungen so zu schreiben, dass sie mit dem jeweils vorherigen Codestand kompatibel bleiben, additive statt destruktive Migrationen, damit ein Rollback auf Anwendungsebene nicht an einer inkompatiblen Datenbank scheitert.

#!/usr/bin/env bash
# rollback.sh: redeploy the previous known-good production tag,
# never edit or force-push tag history under incident pressure
set -euo pipefail

ENVIRONMENT="production"
CURRENT_TAG=$(cat /var/deploy/production/current_tag)
PREVIOUS_TAG=$(git tag --list "v*" --sort=-v:refname | grep -A1 "^${CURRENT_TAG}$" | tail -n1)

if [ -z "${PREVIOUS_TAG}" ]; then
  echo "No previous tag found, manual intervention required" >&2
  exit 1
fi

echo "Rolling back production from ${CURRENT_TAG} to ${PREVIOUS_TAG}"
./deploy.sh "${PREVIOUS_TAG}" "${ENVIRONMENT}"

echo "${PREVIOUS_TAG}" > /var/deploy/production/current_tag
echo "Rollback complete: production now runs ${PREVIOUS_TAG}"

9. Git-basiertes Deployment im Vergleich zu manuellen Methoden

Die folgende Tabelle stellt das manuelle FTP- beziehungsweise lokale Checkout-Deployment dem Git-Tag-basierten CI/CD-Deployment direkt gegenüber, entlang der Kriterien, die im Ernstfall tatsächlich über Ausfallzeit und Wiederherstellungsgeschwindigkeit entscheiden.

In der Summe zeigt der Vergleich, dass Git-basiertes Deployment kein bürokratischer Overhead ist, sondern die Voraussetzung dafür, dass ein Team im Ernstfall in Minuten statt Stunden reagieren kann. Jede Zeile in der Tabelle beschreibt letztlich denselben Mechanismus: Ein unveränderlicher, versionierter Referenzpunkt ersetzt einen unsicheren, von einzelnen Personen abhängigen Prozess.

10. Zusammenfassung

Eine Git-basierte Deployment-Strategie ersetzt Improvisation durch einen deterministischen, nachvollziehbaren Prozess. Git wird zur einzigen Quelle der Wahrheit für Produktionscode, annotierte Tags nach semantischer Versionierung markieren unveränderlich, welcher Codestand tatsächlich live ist, und CI/CD-Pipelines reagieren automatisiert auf Branch-Pushes und Tag-Muster, statt manuell angestoßen zu werden. Das Deployment vom lokalen Entwicklerrechner aus, mit uncommitteten Änderungen, fehlenden Build-Artefakten und inkonsistenten Toolchain-Versionen, entfällt vollständig.

Ein sauberes Branch-zu-Umgebung-Mapping trennt Staging, ephemere Review-Umgebungen und Produktion klar voneinander, während die Magento-CLI-Befehle in fester Reihenfolge, composer install, setup:upgrade, setup:di:compile, setup:static-content:deploy und cache:flush, innerhalb der Pipeline auf exakt der Toolchain laufen, die auch produktiv verwendet wird. Und weil Produktion immer auf einen unveränderlichen Tag zeigt, wird ein Rollback zur einfachen, bereits erprobten Operation: den vorherigen Tag erneut deployen, statt unter Zeitdruck neue Commits zu schreiben.

11. FAQ: Git-basierte Deployment-Strategie für Magento-Shops