Bei einem Webprojekt, dessen Code per FTP oder manuell mit scp auf den Server kopiert wird, gibt es auf eine einfache Frage oft keine Antwort: Welcher Commit läuft live? Tests werden in Eile übersprungen, auf dem Server sammeln sich lokale Änderungen, und ein Rollback erfolgt nach Gefühl. Eine CI/CD-Pipeline führt bei jeder Änderung dieselben Schritte in derselben Reihenfolge aus und beseitigt diese Unsicherheit. Im Folgenden bauen wir in GitHub Actions einen Workflow mit Tests, Build, Artefakt und Bereitstellung per SSH auf, behandeln Geheimnisse, Environment-Schutzregeln und OIDC und nennen zum Schluss die Entsprechungen in GitLab CI.
Phasen einer CI/CD-Pipeline
Eine gut konzipierte Pipeline beantwortet in jeder Phase eine Frage und stoppt, wenn die Antwort negativ ist:
- Validierung: Lässt sich der Code bauen, bestehen Lint und Typprüfung?
- Test: Sind Unit- und Integrationstests erfolgreich?
- Build und Paketierung: Die auszuliefernde Ausgabe (statische Dateien, ein Docker-Container-Image) wird einmal erzeugt und versioniert.
- Bereitstellung: Dieselbe Ausgabe geht zuerst in die Testumgebung und nach der Freigabe in die Produktion.
- Kontrolle nach der Bereitstellung: Antworten Health-Endpunkt und zentrale Seiten?
Grundprinzip: einmal bauen, überall dasselbe bereitstellen. Ein erneuter Build auf dem Produktionsserver birgt das Risiko, dass sich getestete und ausgelieferte Ausgabe unterscheiden; hat sich zwischendurch eine Abhängigkeitsversion geändert, zeigt sich der Fehler erstmals in der Produktion. Eine zur Produktion konsistente Testumgebung ist ein eigenes Thema und wird im Leitfaden Staging-Umgebung einrichten beschrieben.
Beispielhafter Workflow-Aufbau
Der folgende Workflow ist für ein Node.js-basiertes Webprojekt gedacht und wird in der Datei .github/workflows/ci-cd.yml abgelegt. Bei Pull Requests laufen nur Tests; bei einem Push auf den Branch main kommen Build und Produktions-Deployment hinzu. Die Tags @v4 im Beispiel sind gängige Versionen; da mit Laufzeit-Updates der Actions neue Hauptversionen erscheinen können, prüfen Sie auf der Release-Seite jeder Action die aktuelle Hauptversion. Die Node.js-Version im Build-Job muss mit der auf dem Server laufenden übereinstimmen.
name: ci-cd
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node: [22, 24]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci
- run: npm run lint
- run: npm test
build:
needs: test
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: web-dist
path: dist/
retention-days: 7
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: production
url: https://www.example.com
concurrency:
group: deploy-production
cancel-in-progress: false
steps:
- uses: actions/download-artifact@v4
with:
name: web-dist
path: dist
- name: SSH-Konfiguration
env:
SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
run: |
install -m 700 -d ~/.ssh
printf '%s\n' "$SSH_KEY" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
printf '%s\n' "$KNOWN_HOSTS" > ~/.ssh/known_hosts
- name: Hochladen und aktivieren
env:
HOST: ${{ vars.DEPLOY_HOST }}
run: |
RELEASE="$(date +%Y%m%d%H%M%S)-${GITHUB_SHA::7}"
rsync -az --delete dist/ "deploy@$HOST:/var/www/app/releases/$RELEASE/"
ssh "deploy@$HOST" "/var/www/app/bin/activate $RELEASE"
- name: Smoke-Test
run: curl -fsS --retry 5 --retry-delay 3 https://www.example.com/healthz
In dieser Datei bestimmen drei Elemente Reihenfolge und Sicherheit: needs verknüpft die Jobs in einer Reihenfolge, und schlägt ein vorheriger Job fehl, läuft der nächste nicht; die Bedingung if deaktiviert Build und Bereitstellung bei Pull Requests; der permissions-Block ganz oben reduziert die Berechtigung des dem Workflow übergebenen GITHUB_TOKEN auf Lesezugriff. Die Standardberechtigungen des Tokens hängen von den Repository- oder Organisationseinstellungen ab; schränken Sie sie in jedem Workflow ausdrücklich ein. Ein Token mit weitreichenden Rechten ist in der Hand einer kompromittierten Action ein Schreibschlüssel zum Repository.
Test- und Build-Schritte
npm ci führt eine Installation durch, die exakt der Datei package-lock.json entspricht, und meldet einen Fehler, wenn diese Datei und package.json nicht übereinstimmen; deshalb wird es in der CI statt npm install bevorzugt. Die Option cache: npm in actions/setup-node speichert das npm-Cache-Verzeichnis anhand des Hashes der Lock-Datei und stellt es in späteren Läufen wieder her. Für andere Paketmanager oder Build-Ausgaben wird die Action actions/cache nach derselben Logik verwendet; erzeugen Sie den Cache-Schlüssel unbedingt aus dem Hash der Lock-Datei, sonst testen Sie mit veralteten Abhängigkeiten. Grüner Test, falsche Abhängigkeit.
Die Matrix (strategy.matrix) führt dieselben Tests parallel auf mehreren Laufzeitversionen aus; das ist nützlich, um vor dem Upgrade der Serverversion die Kompatibilität mit der neuen Version zu sehen. Bei Integrationstests, die eine Datenbank benötigen, kann der Job-Definition mit einem services:-Block ein temporärer PostgreSQL- oder MariaDB-Container hinzugefügt werden; jeder Lauf beginnt mit einer sauberen Datenbank.
Der Build-Job speichert die Ausgabe mit actions/upload-artifact, der Deployment-Job holt dieselbe Ausgabe mit actions/download-artifact. So wird nach dem getesteten Job genau ein Build erstellt, und die bereitgestellten Dateien sind exakt das Ergebnis dieses Builds. In containerbasierten Projekten wird statt eines Artefakts ein Image mit Versions-Tag in eine Registry übertragen; wie das Image auf dem Server betrieben wird, behandelt der Beitrag Produktivbetrieb mit Docker Compose.
Geheimnisse und Environment-Schutzregeln
In GitHub werden Konfigurationswerte auf drei Ebenen gehalten: Organisation, Repository und Environment. Für nicht sensible Werte (Servername, URL) werden vars, für Passwörter und Schlüssel secrets verwendet. Secrets werden in Logs maskiert, die Maskierung ist jedoch keine Sicherheitsgrenze: Ein Befehl, der den Wert umwandelt (base64, Zerlegung), kann die Maske umgehen.
Das eigentliche Sicherheitstor des Produktions-Deployments ist das Environment. Für ein Environment namens production lassen sich festlegen:
- Erforderliche Prüfer: Der Job startet erst nach Freigabe durch die festgelegte Person oder das Team. Die Verfügbarkeit dieser Funktion in privaten Repositories hängt von Ihrem GitHub-Plan ab.
- Branch-Beschränkung: Nur Läufe aus dem Branch
mainoder von bestimmten Tags dürfen in dieses Environment bereitstellen. - Environment-Secrets: Der Produktionsschlüssel wird nur an den Job übergeben, der dieses Environment nutzt und die Freigabe passiert; Test-Jobs sehen diesen Wert nie.
Die häufigsten Sicherheitsfehler bei Workflow-Reviews:
- Nutzerkontrollierte Werte wie
${{ github.event.pull_request.title }}direkt inrun:zu schreiben; das ist anfällig für Command Injection. Weisen Sie den Wert zuerst mitenv:einer Umgebungsvariablen zu und verwenden Sie ihn in der Shell in Anführungszeichen; der SSH-Schritt im Beispiel folgt diesem Muster. - Actions von Drittanbietern mit einem veränderlichen Tag (
@v1) zu verwenden. Fixieren Sie inoffizielle Actions auf den vollständigen Commit-SHA und führen Sie Updates kontrolliert mit Dependabot durch. - Beim Trigger
pull_request_targetden Code aus dem Fork auszuchecken und auszuführen; dieser Trigger läuft mit Zugriff auf Secrets.
Cloud-Identität mit OIDC
Bei der Bereitstellung in Azure, AWS oder Google Cloud kann statt eines als Secret gespeicherten langlebigen Zugriffsschlüssels OpenID Connect verwendet werden. Der Workflow erhält ein von GitHub signiertes kurzlebiges Token; auf Cloud-Seite wird eine Identität definiert, die den Angaben zu Repository, Branch oder Environment in diesem Token vertraut. In einem Job mit Environment hat das Subject-Feld des Tokens die Form repo:org/repo:environment:production; beschränken Sie die Vertrauensstellung auf Cloud-Seite genau auf diesen Wert.
permissions:
id-token: write
contents: read
steps:
- uses: azure/login@v2
with:
client-id: ${{ vars.AZURE_CLIENT_ID }}
tenant-id: ${{ vars.AZURE_TENANT_ID }}
subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
Für AWS übernimmt die Action aws-actions/configure-aws-credentials dieselbe Rolle mit dem Parameter role-to-assume. Identitätskennungen sind keine Geheimnisse und müssen nicht als Secret gespeichert werden, Berechtigungen sollten auf Cloud-Seite aber nach dem Prinzip der minimalen Rechte vergeben werden. Details finden Sie in der Dokumentation zu GitHub Actions unter „security hardening“.
Methoden der Bereitstellung auf dem Server
| Methode | Geeignet für | Achtung |
|---|---|---|
| Release-Verzeichnis per SSH + rsync | Eigener Linux-Server, PHP oder statische Website | Eingeschränkter Benutzer, festes known_hosts |
Image in die Registry + compose pull/up per SSH |
Containerbasierte Bereitstellung | Das Image-Tag muss zum Commit passen |
| Pull-Modell (der Server holt) | Von außen ist kein SSH zum Server möglich | Agent oder geplanter Task auf dem Server |
| Self-hosted Runner | Ziel liegt im internen Netz | Nicht in öffentlichen Repositories verwenden |
| Cloud-Dienst mit OIDC | App Service, S3, Cloud Run usw. | Vertrauensstellung auf das Environment beschränken |
Bei der Bereitstellung per SSH gelten zwei Regeln. Erstens: Erzeugen Sie den Wert für known_hosts nicht im Workflow spontan mit ssh-keyscan, sondern speichern Sie ihn mit einem vorab geprüften Fingerabdruck als Secret; andernfalls vertrauen Sie bei der ersten Verbindung einem dazwischengeschalteten Server. Zweitens: Der Deployment-Benutzer darf nur in das Anwendungsverzeichnis schreiben, und sudo-Rechte sind auf den einen benötigten Befehl (etwa den Reload von PHP-FPM) zu beschränken.
Das Verzeichnis releases/ und das Skript activate im Beispiel sorgen dafür, dass jede Version in ein eigenes Verzeichnis hochgeladen und anschließend in einem Schritt aktiviert wird. Wie dieser Wechsel unterbrechungsfrei erfolgt und welche Alternativen wie Blue-Green oder Rolling es gibt, ist Thema des Leitfadens Zero-Downtime-Deployment; hier konzentrieren wir uns auf die Pipeline selbst.
Entsprechungen in GitLab CI
Beim Umzug derselben Pipeline nach GitLab entsprechen sich die Konzepte weitgehend; Syntax und die Lizenzstufe einiger Funktionen unterscheiden sich:
| GitHub Actions | GitLab CI/CD |
|---|---|
.github/workflows/*.yml |
.gitlab-ci.yml |
jobs und needs |
stages und needs |
runs-on |
image und Runner-tags |
on: und if: |
rules: und workflow:rules |
actions/upload-artifact |
artifacts: paths |
actions/cache |
cache: key / paths |
secrets / vars |
CI/CD-Variablen (protected, masked) |
| Environment-Schutzregeln | Protected environments, deployment approvals |
concurrency |
resource_group |
id-token: write (OIDC) |
id_tokens |
Der entscheidende Unterschied in GitLab: Geschützte (protected) Variablen werden nur an Jobs übergeben, die auf geschützten Branches und Tags laufen; Produktionsschlüssel so zu markieren, schafft eine ähnliche Grenze wie die Environment-Secrets in GitHub. Details finden Sie in der GitLab-Dokumentation.
Auch nach der Einrichtung braucht die Pipeline Pflege. Beobachten Sie langsamer werdende Tests, überprüfen Sie den Cache, halten Sie die Action-Versionen aktuell; eine Pipeline, die zwanzig Minuten dauert, treibt das Team zu Abkürzungen. Um einem bestehenden Projekt CI/CD hinzuzufügen oder manuelle Veröffentlichungen zu automatisieren, sehen Sie sich unsere Leistungsseite CI/CD und Web-DevOps-Automatisierung an.
Häufig gestellte Fragen
Warum kann man bei Pull Requests aus Forks nicht auf Geheimnisse zugreifen?
Aus Sicherheitsgründen gibt GitHub Workflows vom Typ pull_request, die durch Pull Requests aus Forks ausgelöst werden, keine Repository-Secrets und stellt GITHUB_TOKEN nur lesend bereit. Das ist ein bewusster Schutz. Mit pull_request_target lässt sich diese Grenze umgehen, doch wer bei diesem Trigger den Code aus dem Fork auscheckt und ausführt, riskiert die Kompromittierung der Secrets.
Sollte ich für die Bereitstellung einen SSH-Schlüssel oder OIDC verwenden?
Ist das Ziel ein Cloud-Anbieter (Azure, AWS, Google Cloud), sollte OIDC bevorzugt werden; es wird kein langlebiger Schlüssel gespeichert, und eine kurzlebige Identität wird bei jedem Lauf neu erzeugt. Für die Bereitstellung auf Ihrem eigenen Linux-Server ist ein SSH-Schlüssel die praktische Wahl; binden Sie den Schlüssel an einen eingeschränkten Benutzer, der nur für Deployments vorgesehen ist, und rotieren Sie ihn regelmäßig.
Wie verhindere ich, dass zwei Bereitstellungen gleichzeitig laufen?
Definieren Sie für den Deployment-Job eine concurrency-Gruppe und lassen Sie cancel-in-progress auf false. Dann wartet ein zweiter Lauf in derselben Gruppe, bis der erste abgeschlossen ist; eine neue Bereitstellung startet nicht auf einer halb fertigen. In der Gruppe wird gleichzeitig nur ein wartender Lauf gehalten; kommt ein neuerer, wird der ältere wartende abgebrochen, sodass der letzte Commit bereitgestellt wird.
Sollte ich Tests und Bereitstellung in einem Workflow oder in getrennten Dateien halten?
In kleinen und mittleren Projekten ist es sowohl lesbar als auch sicher, mit needs verknüpfte Jobs in einem Workflow zu halten, denn so ist das getestete Artefakt dasselbe wie das bereitgestellte. Wächst das Projekt, können gemeinsame Schritte mit wiederverwendbaren Workflows (workflow_call) in eine separate Datei ausgelagert werden.