Dieses GitHub Actions Tutorial zeigt dir, wie du in einer einzigen YAML-Datei einen Workflow baust, der bei jedem Push deinen Code testet, auf mehreren Node-Versionen gleichzeitig läuft, Abhängigkeiten zwischenspeichert, Secrets sicher verwendet und am Ende ein Ergebnis ablegt. GitHub Actions ist die eingebaute Automatisierung von GitHub: Du beschreibst, wann etwas passieren soll und was dann passiert, und GitHub stellt dir dafür eine frische virtuelle Maschine bereit. Kein eigener Server, kein Jenkins, keine Installation.
Wir haben das nicht aus der Dokumentation abgeschrieben. Am 16. November 2026 haben wir ein privates Wegwerf-Repository angelegt, darin genau die Workflows aus diesem Artikel laufen lassen, Fehler absichtlich provoziert und alles mitgeschrieben. Danach haben wir das Repo wieder gelöscht. Fünf Befunde vorweg:
1. Ein einziges falsch gesetztes Doppelpunkt-Leerzeichen in einer
run:-Zeile lässt den ganzen Workflow in 0 Sekunden scheitern. GitHub sagt dazu nur „This run likely failed because of a workflow file issue“. Das Werkzeug actionlint zeigte uns Zeile und Spalte sofort.2. GitHub schwärzt Secrets im Log zuverlässig, auch in Base64. Rückwärts geschrieben oder mit Leerzeichen zwischen den Zeichen stand unser Test-Secret aber im Klartext im Log.
3. Ein Secret, das es gar nicht gibt, führt zu keinem Fehler. Der Wert ist einfach leer, Länge 0. Der Workflow läuft weiter, als wäre alles in Ordnung.
4. Viele Anleitungen nutzen noch
actions/checkout@v4. Auf den heutigen Runnern gibt das eine Warnung, weil diese Version auf Node.js 20 basiert, das GitHub inzwischen zwangsweise auf Node 24 umleitet. Aktuell sind checkout v7 und setup-node v7.5. Der Standard-Runner
ubuntu-latestwar bei uns Ubuntu 26.04.1 LTS mit 2 CPU-Kernen, rund 7,7 GB RAM und 15 GB freiem Plattenplatz. Der komplette erste Lauf mit drei Node-Versionen dauerte 14 Sekunden.

Was ist GitHub Actions? Die Begriffe in diesem Tutorial
Bevor wir die erste Datei schreiben, lohnt sich ein Blick auf die fünf Begriffe, die in jedem GitHub Actions Tutorial auftauchen. Wer die einmal sauber auseinanderhält, versteht auch fremde Workflows auf Anhieb.
Workflow. Eine YAML-Datei im Ordner .github/workflows/ deines Repositorys. Jede Datei dort ist ein eigener Workflow. Der Dateiname ist egal, Hauptsache die Endung ist .yml oder .yaml. Wenn dir YAML noch fremd ist: Wir haben die Unterschiede und Fallen in YAML vs JSON ausführlich gemessen. Bei GitHub Actions sind sie besonders relevant, wie Befund 1 zeigt.
Event (Trigger). Das Ereignis, das den Workflow startet. Die häufigsten sind push (jemand pusht Commits), pull_request (ein Pull Request wird geöffnet oder aktualisiert), schedule (Zeitplan im Cron-Format) und workflow_dispatch (manueller Start per Knopf oder API).
Job. Eine Gruppe von Schritten, die auf einer Maschine läuft. Ein Workflow kann mehrere Jobs haben. Ohne weitere Angabe laufen sie parallel, jeder auf seiner eigenen, frischen Maschine. Mit needs: legst du eine Reihenfolge fest.
Step. Ein einzelner Schritt in einem Job. Entweder ein Shell-Befehl (run:) oder eine fertige, wiederverwendbare Action (uses:). Steps eines Jobs teilen sich das Dateisystem, Jobs untereinander nicht.
Runner. Die Maschine, auf der ein Job läuft. GitHub stellt Runner mit Linux, Windows und macOS bereit (runs-on: ubuntu-latest). Du kannst auch eigene Rechner als Self-hosted Runner anmelden.
Das Prinzip dahinter heißt Continuous Integration (CI): Jede Änderung wird automatisch gebaut und getestet, bevor sie in den Hauptzweig kommt. Kommt automatisches Ausliefern dazu, spricht man von Continuous Delivery oder Continuous Deployment (CD). GitHub Actions kann beides. Grundlage ist immer ein Git-Repository. Wer die Befehle drumherum auffrischen will, findet sie in unserer Git Befehle Liste, die Grundidee in Was ist Git?.
Englischsprachig: „GitHub Actions Explained: Everything You Need to Know“ von DevOps with Flavius (September 2026) erklärt Zeile für Zeile, was in einer Workflow-Datei passiert. Gut für alle, die bisher YAML aus anderen Repos kopiert haben, ohne jede Zeile zu verstehen. Ein gleichwertig aktuelles deutsches Video haben wir nicht gefunden.
Unser Testaufbau für dieses GitHub Actions Tutorial
Damit die Zahlen in diesem Artikel nachprüfbar sind, hier der genaue Aufbau:
- Repository: neu angelegt, privat, nur für diesen Test, danach gelöscht.
- Projekt: ein winziges Node.js-Paket mit einer Funktion
sum(a, b)und einem Test mit dem eingebauten Test-Runner (node --test). Keine Frameworks, damit die Messung zeigt, was GitHub Actions kostet, und nicht, was ein großes Projekt kostet. - Runner:
ubuntu-latest, also der kostenlose Standard-Runner. - Gemessen: Laufzeiten aus der GitHub-API (
startedAt/completedAtje Job), Runner-Daten pernproc,free -m,df -hund/etc/os-releasedirekt im Workflow, Log-Inhalte übergh run view --log. - Datum: 16.11.2026, Runner-Version 2.338.2, Runner-Image ubuntu-26.04, Version 20261111.196.1.
Ein neues Repository hatte bei uns übrigens den Standard default_workflow_permissions: read. Das heißt: Das automatische Token, das jeder Workflow bekommt, darf ab Werk nur lesen. Bei älteren Repositorys kann das anders eingestellt sein. Dazu weiter unten mehr.
Schritt 1: Die erste Workflow-Datei
Lege im Repository die Datei .github/workflows/ci.yml an. Das ist der kleinste sinnvolle Workflow, den wir empfehlen:
name: CI
on:
push:
branches: [main]
pull_request:
workflow_dispatch:
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm test
Zeile für Zeile:
name: CIist der Anzeigename im Actions-Tab.on:legt fest, wann der Workflow startet. Hier: bei Pushes aufmain, bei jedem Pull Request und manuell über den Knopf „Run workflow“.permissions: contents: readbeschränkt das automatische Token auf Lesen. Das schreiben wir immer explizit hin, auch wenn das Repo schon so eingestellt ist. Dann stimmt es auch, wenn jemand die Datei in ein anderes Repo kopiert.runs-on: ubuntu-latestwählt den Runner.timeout-minutes: 10bricht einen hängenden Job nach zehn Minuten ab. Ohne diese Zeile gilt das Standardlimit von 360 Minuten. Ein Test, der auf eine nie kommende Netzwerkantwort wartet, verbrennt sonst sechs Stunden Rechenzeit.actions/checkout@v7holt deinen Code auf den Runner. Ohne diesen Schritt ist das Arbeitsverzeichnis leer, ein häufiger Anfängerfehler.actions/setup-node@v7installiert die gewünschte Node-Version und kümmert sich mitcache: npmum den Zwischenspeicher.npm ciinstalliert die Abhängigkeiten exakt nachpackage-lock.json. Anders alsnpm installverändert es die Lockdatei nie und bricht ab, wenn sie nicht zurpackage.jsonpasst. Genau das willst du in CI.
Committe und pushe die Datei. Im Tab Actions deines Repositorys erscheint sofort ein neuer Lauf. Du kannst ihn auch im Terminal verfolgen, wenn du die GitHub-CLI installiert hast:
gh run list
gh run watch
gh run view --log

Welche Action-Version ist aktuell?
Viele Tutorials, auch neue, zeigen noch actions/checkout@v4 und actions/setup-node@v4. Das funktioniert, erzeugt aber auf den heutigen Runnern diese Warnung, die wir in jedem Job unseres ersten Laufs hatten:
##[warning]Node.js 20 is deprecated. The following actions target Node.js 20
but are being forced to run on Node.js 24: actions/checkout@v4, ...
Die Actions selbst sind JavaScript-Programme und laufen in einer bestimmten Node-Version. Die alten Hauptversionen wurden für Node 20 gebaut. GitHub führt sie inzwischen trotzdem mit Node 24 aus, meistens klappt das, garantiert ist es nicht. Am Tag unserer Messung waren laut GitHub-API die neuesten Versionen:
| Action | Neueste Version | Veröffentlicht |
|---|---|---|
actions/checkout | v7.0.1 | 20.07.2026 |
actions/setup-node | v7.1.0 | 08.10.2026 |
actions/upload-artifact | v7.0.2 | 07.10.2026 |
actions/cache | v6.1.0 | 26.06.2026 |
Die Tabelle altert natürlich. Prüfen kannst du das jederzeit selbst: gh api repos/actions/checkout/releases/latest -q .tag_name. Oder du lässt dir Updates automatisch vorschlagen, siehe Abschnitt Dependabot weiter unten.
Schritt 2: Was auf dem Runner wirklich passiert
Wir wollten wissen, was für eine Maschine man bei ubuntu-latest eigentlich bekommt. Also haben wir einen Schritt eingebaut, der genau das ausgibt:
- name: Runner info
run: |
nproc
free -m | head -2
df -h / | tail -1
uname -r
grep PRETTY /etc/os-release
Das Ergebnis, identisch auf allen drei parallel gestarteten Maschinen:
| Messwert | Ergebnis |
|---|---|
| Betriebssystem | Ubuntu 26.04.1 LTS |
| Kernel | 7.0.0-1019-azure |
CPU-Kerne (nproc) | 2 |
| Arbeitsspeicher | 7.931 MB gesamt, ca. 6.900 MB verfügbar |
| Systemplatte | 72 GB, davon 15 GB frei |
| Cloud | Azure |
Zwei Dinge fallen auf. Erstens: ubuntu-latest wandert mit. Wer sich auf eine bestimmte Ubuntu-Version verlässt, sollte sie fest angeben, etwa runs-on: ubuntu-24.04. Sonst kann ein Workflow, der monatelang lief, an einem Montag plötzlich mit neuen Paketversionen laufen. Zweitens: 15 GB frei klingt viel, ist aber schnell weg, wenn du große Docker-Images baust oder Modelle herunterlädst. Wie man Images klein hält, erklären wir in Was ist Docker? und im Praxisteil von Docker Compose Beispiel.
Wichtig für das Verständnis: Jeder Job bekommt eine brandneue Maschine. Nach dem Job wird sie weggeworfen. Nichts, was du dort installierst oder speicherst, ist beim nächsten Lauf noch da, außer du nutzt bewusst Cache oder Artifacts.
Schritt 3: Matrix, also mehrere Versionen gleichzeitig testen
Eine der stärksten Funktionen von GitHub Actions ist die Matrix. Statt einen Job dreimal hinzuschreiben, beschreibst du die Varianten:
jobs:
test:
runs-on: ubuntu-latest
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
node: [20, 22, 24]
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci
- run: npm test
GitHub erzeugt daraus drei Jobs: test (20), test (22) und test (24). Sie starten gleichzeitig. Bei uns lief der allererste Lauf so ab:
| Job | Start | Ende | Dauer |
|---|---|---|---|
| test (20) | 08:03:07 | 08:03:18 | 11 s |
| test (22) | 08:03:07 | 08:03:14 | 7 s |
| test (24) | 08:03:07 | 08:03:16 | 9 s |
Der gesamte Workflow stand in der Übersicht mit 14 Sekunden. Drei Node-Versionen in der Zeit, in der man lokal gerade mal npm install tippt.
Du kannst Matrix-Dimensionen auch kombinieren, etwa os: [ubuntu-latest, windows-latest] und node: [22, 24]. Dann entstehen 2 × 2 = 4 Jobs. Bei privaten Repositorys zählt jeder davon gegen dein Kontingent, und Windows- und macOS-Runner werden teurer abgerechnet als Linux. Also nur so viele Kombinationen wie nötig.

fail-fast: Was passiert, wenn eine Variante scheitert?
fail-fast steht ab Werk auf true. Das bedeutet: Scheitert ein Matrix-Job, bricht GitHub die anderen ab. Das spart Rechenzeit, nimmt dir aber Information. Wir haben das zweimal getestet, mit einem Test, der absichtlich nur auf Node 20 fehlschlägt.
Versuch 1, alle Jobs schnell: Node 20 scheiterte, Node 22 und 24 waren zu diesem Zeitpunkt aber schon fertig und blieben grün. Es gab nichts mehr abzubrechen.
Versuch 2, Node 22 und 24 künstlich um 25 Sekunden verlangsamt: Node 20 scheiterte um 08:09:34. Node 22 und 24 wurden kurz danach mit Status cancelled beendet. Ein dritter Job, der per needs: von den Tests abhing, wurde skipped.
Die Konsequenz: Mit fail-fast: true weißt du nach einem roten Lauf nicht, ob nur Node 20 betroffen ist oder alle Versionen. Wir setzen deshalb bei Matrix-Tests fast immer fail-fast: false. Bei teuren Builds, die ohnehin alle am selben Fehler scheitern würden, ist true dagegen sinnvoll.
Schritt 4: Cache, damit nicht jeder Lauf alles neu lädt
Bei jedem Lauf startet der Runner leer. Ohne Cache lädt npm ci alle Pakete jedes Mal frisch aus dem Netz. actions/setup-node mit cache: npm speichert das npm-Cache-Verzeichnis zwischen, mit der Lockdatei als Schlüssel.
In unserem Log sieht man genau, wie das funktioniert. Im allerersten Lauf meldete der Node-24-Job:
npm cache is not found
...
Cache saved with the key: node-cache-Linux-x64-npm-ecfe7b8f...
Der Node-20-Job, der ein paar Sekunden später an derselben Stelle war, bekam schon:
Cache hit for: node-cache-Linux-x64-npm-ecfe7b8f...
Cache Size: ~0 MB (356579 B)
Cache restored successfully
Zwei Erkenntnisse daraus. Erstens: Der Cache wird im selben Lauf schon zwischen parallelen Jobs geteilt, sobald der erste ihn gespeichert hat. Zweitens: Bei unserem Mini-Projekt war der Cache nur 357 KB groß. Hier bringt er praktisch keine Zeitersparnis. Bei echten Projekten mit hunderten MB node_modules-Abhängigkeiten sieht das anders aus.
Was du wissen solltest:
- Der Schlüssel enthält einen Hash der Lockdatei. Ändert sich
package-lock.json, gibt es einen neuen Cache. - Ein Cache wird nicht überschrieben, wenn der Schlüssel schon existiert. Das Log sagt dann: „Cache hit occurred on the primary key …, not saving cache.“
- Laut GitHub-Dokumentation hat jedes Repository ein eigenes Cache-Kontingent von 10 GB, getrennt von Artifacts und Packages. Alte Einträge werden verdrängt.
- Cache ist kein Ort für Build-Ergebnisse, die du später brauchst. Dafür gibt es Artifacts.
Schritt 5: Secrets richtig verwenden
Früher oder später braucht dein Workflow ein Passwort, einen API-Schlüssel oder einen SSH-Key, zum Beispiel für einen Deploy. Das gehört niemals in die YAML-Datei, sondern in die Secrets des Repositorys: Settings → Secrets and variables → Actions → New repository secret. Oder im Terminal:
gh secret set DEPLOY_KEY < ~/.ssh/deploy_key
Im Workflow greifst du darüber zu, am besten über eine Umgebungsvariable:
- name: Etwas mit dem Secret tun
env:
MY_SECRET: ${{ secrets.DEMO_SECRET }}
run: ./scripts/deploy.sh
GitHub verspricht, Secrets im Log automatisch zu schwärzen. Wir wollten wissen, wie weit das reicht. Also haben wir ein Test-Secret mit 18 Zeichen angelegt und es absichtlich auf verschiedene Arten ausgegeben:
- name: Masking-Grenzen
env:
MY_SECRET: ${{ secrets.DEMO_SECRET }}
run: |
echo "direkt: $MY_SECRET"
echo "base64: $(echo -n "$MY_SECRET" | base64)"
echo "rueckwaerts: $(echo -n "$MY_SECRET" | rev)"
echo "mit Leerzeichen: $(echo -n "$MY_SECRET" | sed 's/./& /g')"
Das Log zeigte:
direkt: ***
base64: ***
rueckwaerts: frewgew-321-mieheg
mit Leerzeichen: g e h e i m - 1 2 3 - w e g w e r f
Die Base64-Variante wurde erkannt und geschwärzt, das hat uns positiv überrascht. Jede andere Umformung aber nicht. In der Praxis passiert so etwas selten absichtlich, aber unabsichtlich schon: Ein Skript gibt eine URL mit eingebettetem Token URL-kodiert aus, ein Tool schreibt einen JSON-Dump mit escapten Zeichen, ein Debug-Modus zeigt Teilstrings. Die Schwärzung ist ein Sicherheitsnetz, kein Schutzkonzept. Das eigentliche Schutzkonzept lautet: Secrets nicht ausgeben, und Logs von privaten Repos trotzdem wie vertrauliche Daten behandeln.

Die stille Falle: fehlende Secrets
Zweiter Test: Wir haben auf ein Secret zugegriffen, das es gar nicht gibt (secrets.GIBT_ES_NICHT). Ergebnis:
fehlt: '' (Laenge 0)
Kein Fehler, keine Warnung, der Schritt war grün. Ein Tippfehler im Secret-Namen fällt also erst auf, wenn der Deploy sich mit einem leeren Passwort anmeldet und irgendwo weiter hinten scheitert, im schlimmsten Fall mit einer verwirrenden Fehlermeldung. Wir bauen deshalb in Deploy-Jobs eine Prüfung ganz an den Anfang:
- name: Secrets vorhanden?
env:
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
run: |
if [ -z "$DEPLOY_KEY" ]; then
echo "::error::DEPLOY_KEY fehlt oder ist leer"
exit 1
fi
Wichtig zu wissen: Bei Pull Requests aus Forks bekommen Workflows aus Sicherheitsgründen keine Secrets. Auch da sind sie dann einfach leer. Mit dieser Prüfung siehst du sofort, warum ein Fork-PR rot ist.
Schritt 6: Das GITHUB_TOKEN und seine Rechte
Jeder Workflow-Lauf bekommt automatisch ein kurzlebiges Token, erreichbar als secrets.GITHUB_TOKEN oder github.token. Damit kann der Workflow mit deinem Repository sprechen: Code auschecken, Kommentare schreiben, Releases anlegen, je nach Rechten.
Mit permissions: contents: read haben wir im Test versucht, aus dem Workflow heraus einen Branch zu pushen:
fatal: unable to access 'https://github.com/.../': The requested URL returned error: 403
PUSH ABGELEHNT
Genau so soll es sein. Gib jedem Workflow nur die Rechte, die er braucht, und zwar so spät und so eng wie möglich. Wenn ein einzelner Job schreiben muss, etwa um ein Release anzulegen, setze die Rechte nur auf diesem Job:
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- ...
Warum das so wichtig ist: Jede Action, die du mit uses: einbindest, ist fremder Code, der mit diesem Token läuft. Wird eine beliebte Action kompromittiert, kann ein Token mit Schreibrechten deinen Code verändern. Deshalb auch der Rat, Actions von Drittanbietern nicht nur auf ein Tag wie @v3, sondern auf einen vollen Commit-Hash festzunageln, zum Beispiel uses: owner/action@a1b2c3d…. Tags lassen sich nachträglich verschieben, Commit-Hashes nicht. Bei den offiziellen actions/* ist das Risiko geringer, viele Teams pinnen sie trotzdem. Mehr zum Grundprinzip in unserem Artikel IT-Sicherheitslücken.
Schritt 7: Concurrency, damit sich Läufe nicht stapeln
Wer schnell hintereinander pusht, startet mehrere Läufe für denselben Branch. Meistens interessiert nur der letzte. Mit concurrency sorgst du dafür, dass ein neuer Lauf den alten abbricht:
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
Unser Test: zwei Pushes im Abstand von etwa vier Sekunden. Der erste Lauf wurde nach 9 Sekunden mit Status cancelled beendet, alle seine Jobs ebenfalls. Nur der zweite lief zu Ende.
Vorsicht bei Deploy-Workflows: Dort willst du einen laufenden Deploy meist nicht mittendrin abbrechen. Für Deploys setzen wir deshalb cancel-in-progress: false. Dann wartet der neue Lauf, bis der alte fertig ist.
Schritt 8: Artifacts, also Ergebnisse aufbewahren
Wenn ein Job etwas erzeugt, das du behalten oder in einem späteren Job brauchen willst (ein Build-Ordner, ein Testbericht, ein Paket), lädst du es als Artifact hoch:
- name: Build
run: mkdir -p out && date -u > out/build.txt
- uses: actions/upload-artifact@v7
with:
name: build-output
path: out/
retention-days: 1
In unserem Test war das Artifact 163 Bytes groß und hatte laut API ein Ablaufdatum genau einen Tag später. Ohne retention-days gilt die Voreinstellung des Repositorys, standardmäßig 90 Tage. Gerade bei privaten Repositorys lohnt sich ein kurzer Wert: Speicherplatz für Artifacts wird laut GitHub-Dokumentation stundenweise aufaddiert, auch wenn du sie später löschst.
Ein zweiter Job kann das Artifact mit actions/download-artifact wieder herunterladen. Das ist der übliche Weg, um einen Build-Job und einen Deploy-Job zu trennen: Der eine baut, der andere liefert genau dieses Ergebnis aus.
Die häufigste Falle: kaputtes YAML
Jetzt zum Befund, der uns am meisten Zeit gekostet hat. Wir wollten im Workflow eine Zeile wie diese ausgeben:
- name: Fehlendes Secret
run: echo "fehlt: '${{ secrets.GIBT_ES_NICHT }}'"
Sieht harmlos aus. Nach dem Push: Lauf rot, Dauer 0 Sekunden, kein einziger Job gestartet. Die Weboberfläche und gh run view sagten nur:
X This run likely failed because of a workflow file issue.
Keine Zeilennummer, kein Hinweis. Die Ursache: In YAML leitet ein Doppelpunkt mit Leerzeichen (: ) eine neue Zuordnung ein. In einem ungequoteten Wert nach run: ist das verboten. Unsere Zeile enthielt fehlt: ', und damit war die ganze Datei ungültig.
Gefunden hat den Fehler actionlint, ein freies Prüfwerkzeug speziell für GitHub-Actions-Dateien. Wir haben es lokal per Docker gestartet:
docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:latest
Ausgabe:
.github/workflows/ci.yml:42:24: could not parse as YAML:
mapping values are not allowed in this context [syntax-check]
Zeile 42, Spalte 24, genau die Stelle. Die Lösung ist einfach: mehrzeilige Schreibweise mit | verwenden. Dann ist der Inhalt ein Textblock, und Doppelpunkte sind erlaubt:
- name: Fehlendes Secret
run: |
echo "fehlt: '${{ secrets.GIBT_ES_NICHT }}'"
Unsere Faustregel seit diesem Test: Jede run:-Zeile, die mehr als einen einfachen Befehl enthält, bekommt |. Und actionlint läuft vor jedem Push, entweder als Editor-Erweiterung oder als Pre-Commit-Hook. actionlint findet übrigens nicht nur Syntaxfehler, sondern auch Tippfehler in Ausdrücken, unbekannte Event-Namen und typische Shell-Fehler über das eingebaute shellcheck.
Schritt 9: Deploy mit GitHub Actions
Ein GitHub Actions Tutorial ohne Deploy wäre unvollständig. Der einfachste Weg auf einen eigenen Server ist SSH mit einem eigenen Deploy-Schlüssel. Das Grundmuster:
name: Deploy
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: deploy-production
cancel-in-progress: false
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
- run: npm ci
- run: npm test
- run: npm run build
- uses: actions/upload-artifact@v7
with:
name: dist
path: dist/
retention-days: 3
deploy:
runs-on: ubuntu-latest
needs: test
environment: production
steps:
- uses: actions/download-artifact@v7
with:
name: dist
path: dist/
- name: Secrets vorhanden?
env:
KEY: ${{ secrets.DEPLOY_SSH_KEY }}
run: |
[ -n "$KEY" ] || { echo "::error::DEPLOY_SSH_KEY fehlt"; exit 1; }
- name: Auf Server kopieren
env:
KEY: ${{ secrets.DEPLOY_SSH_KEY }}
HOST: ${{ secrets.DEPLOY_HOST }}
KNOWN: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
run: |
install -m 700 -d ~/.ssh
echo "$KEY" > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519
echo "$KNOWN" > ~/.ssh/known_hosts
rsync -a --delete dist/ "deploy@$HOST:/var/www/app/"
Was hier steckt:
needs: testsorgt dafür, dass nur ausgeliefert wird, wenn die Tests grün sind.environment: productionverknüpft den Job mit einer Umgebung. In den Repository-Einstellungen kannst du dort Secrets ablegen, die nur dieser Job sieht, und eine manuelle Freigabe verlangen, bevor er startet.- Eigener Schlüssel nur für den Deploy. Wie man einen erzeugt, steht in SSH-Key erstellen. Auf dem Server sollte der Schlüssel einem eingeschränkten Benutzer gehören, nicht root.
known_hostsals Secret stattStrictHostKeyChecking=no. Sonst würdest du dich blind mit jedem Server verbinden, der sich als deiner ausgibt. Den Eintrag bekommst du mitssh-keyscan dein-server.de.rsync --deletesynchronisiert genau den Inhalt vondist/. Achtung auf die Schrägstriche am Ende:dist/kopiert den Inhalt,distden Ordner selbst.
Auf dem Server läuft die Anwendung dann zum Beispiel als systemd-Dienst. Wie das geht, haben wir in systemd Service erstellen gezeigt. Wer keinen eigenen Deploy-Weg bauen will, kann auch eine Self-Hosted-PaaS dazwischenschalten, die bei jedem Push selbst baut. Unsere Erfahrungen damit stehen in Coolify Erfahrungen.

Ebenfalls englischsprachig: Mickey Gousset zeigt in „Getting Started with GitHub Actions: 5 Ways to Run a GitHub Actions Workflow“ (Oktober 2026), welche Trigger es gibt und warum ein Workflow manchmal startet und manchmal nicht. Das passt direkt zu den Abschnitten über on: und concurrency.
Weitere Trigger: Zeitplan, manueller Start, Pfadfilter
Neben push und pull_request gibt es ein paar Trigger, die man im Alltag ständig braucht.
Zeitplan. Ein Workflow, der jede Nacht läuft, etwa für Abhängigkeits-Checks:
on:
schedule:
- cron: "17 3 * * *"
Die Zeit ist immer UTC. Wir wählen bewusst eine krumme Minute wie 17, weil zur vollen Stunde besonders viele Workflows weltweit starten und geplante Läufe dann verspätet beginnen können. Ein Detail, das man kennen sollte: Bei öffentlichen Repositorys ohne Aktivität deaktiviert GitHub geplante Workflows nach einer Weile automatisch. Das Cron-Format selbst ist dasselbe wie unter Linux, erklärt in Cronjob erstellen.
Manueller Start mit Eingaben. workflow_dispatch kann Parameter abfragen:
on:
workflow_dispatch:
inputs:
ziel:
description: "Wohin deployen?"
type: choice
options: [staging, production]
Im Workflow liest du den Wert mit inputs.ziel aus.
Pfadfilter. Wenn sich nur die Doku ändert, muss nicht die ganze Testsuite laufen:
on:
push:
branches: [main]
paths-ignore:
- "docs/**"
- "**.md"
Vorsicht in Kombination mit Branch-Schutzregeln: Wenn ein Pflicht-Check wegen eines Pfadfilters gar nicht startet, bleibt ein Pull Request im Zustand „Expected — Waiting for status“ hängen. Für Pflicht-Checks ist ein Job, der kurz prüft und dann grün meldet, oft die robustere Lösung.
Was kostet GitHub Actions?
Die ehrliche Kurzfassung, nach der aktuellen Abrechnungsseite von GitHub:
- Öffentliche Repositorys: Standard-Runner sind kostenlos, ohne Minutenzähler.
- Private Repositorys: Jeder Plan enthält ein monatliches Kontingent an Rechenleistung. Was darüber hinausgeht, wird dem Besitzer des Repositorys berechnet, nicht der Person, die den Lauf ausgelöst hat. Linux-Runner sind am günstigsten, Windows und macOS werden höher gewichtet.
- Speicher: Artifacts und GitHub Packages teilen sich ein Speicherkontingent, abgerechnet nach GB-Stunden. Der Cache hat davon getrennt 10 GB pro Repository.
- Self-hosted Runner: verbrauchen kein Kontingent. Du bezahlst stattdessen deinen eigenen Server.
Die genauen Freikontingente ändern sich und hängen vom Plan ab, deshalb nennen wir hier bewusst keine Minutenzahlen. Aktuell nachlesen kannst du sie in den GitHub-Docs unter „GitHub Actions billing“. Für Einsteiger-Projekte gilt praktisch: Ein kleines privates Repo mit einem Workflow wie in diesem Tutorial verbraucht pro Lauf ein paar Sekunden bis wenige Minuten. Teuer wird es erst mit großen Matrizen, langen Builds oder vergessenen timeout-minutes.
Self-hosted Runner: wann sie sich lohnen
Ein Self-hosted Runner ist ein eigener Rechner, auf dem du das Runner-Programm von GitHub installierst. Er holt sich dann Jobs aus deinem Repository. Das lohnt sich, wenn du viel Rechenzeit brauchst, besondere Hardware (GPU, viel RAM) oder Zugriff auf ein internes Netz, in das GitHubs Maschinen nicht kommen.
Der Haken ist die Sicherheit: Ein Self-hosted Runner führt den Code aus, der im Workflow steht. Bei öffentlichen Repositorys kann jeder einen Pull Request öffnen, und je nach Konfiguration läuft dessen Code dann auf deiner Maschine. GitHub rät deshalb ausdrücklich davon ab, Self-hosted Runner mit öffentlichen Repositorys zu verwenden. Für private Repos gilt: eigene, isolierte Maschine oder VM, kein Server, auf dem auch Produktivdaten liegen, und regelmäßig neu aufsetzen. Die Grundlagen zu Serverwahl und Absicherung findest du in Was ist ein VPS? und Linux-Server einrichten.
Dependabot: Actions automatisch aktuell halten
Erinnerst du dich an die Node-20-Warnung? Damit dir das nicht wieder passiert, kann Dependabot neue Versionen deiner Actions automatisch als Pull Request vorschlagen. Lege dazu .github/dependabot.yml an:
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
Dependabot findet alle uses:-Zeilen und öffnet einmal pro Woche einen Pull Request, wenn es Neues gibt. Dein CI-Workflow testet diesen PR dann automatisch. Auch festgenagelte Commit-Hashes werden so aktualisiert. Das ist der Grund, warum Hash-Pinning im Alltag nicht nervt.
Unsere Checkliste für jeden neuen Workflow
Aus dem Test und aus unserer eigenen Arbeit mit Workflows sind diese Punkte übrig geblieben, die wir inzwischen jedes Mal abhaken:
permissions:explizit setzen, ab Werkcontents: read, Schreibrechte nur auf einzelnen Jobs.timeout-minutes:auf jedem Job.- Aktuelle Action-Versionen, keine Node-20-Warnungen im Log.
|für jederun:-Zeile mit mehr als einem einfachen Befehl.- actionlint vor dem Push.
- Secrets auf Vorhandensein prüfen, bevor sie benutzt werden.
- Secrets nie ausgeben, auch nicht umgeformt.
concurrencyfür CI mitcancel-in-progress: true, für Deploys mitfalse.fail-fast: falsebei Matrix-Tests, wenn du wissen willst, welche Varianten betroffen sind.retention-daysbei Artifacts kurz halten.- Runner-Version fest angeben (
ubuntu-24.04), wenn der Build davon abhängt. - Dependabot für github-actions aktivieren.
Häufige Fragen zum GitHub Actions Tutorial
Was ist GitHub Actions einfach erklärt?
GitHub Actions ist die eingebaute Automatisierung von GitHub. Du legst eine YAML-Datei in .github/workflows/ ab, die beschreibt, bei welchem Ereignis (etwa einem Push) welche Befehle laufen sollen. GitHub startet dafür eine frische virtuelle Maschine, führt die Befehle aus und zeigt dir das Ergebnis als grünen oder roten Haken am Commit.
Ist GitHub Actions kostenlos?
Für öffentliche Repositorys sind die Standard-Runner kostenlos. Für private Repositorys enthält jeder GitHub-Plan ein monatliches Kontingent, darüber hinaus wird abgerechnet. Self-hosted Runner verbrauchen kein Kontingent. Die aktuellen Zahlen stehen in den GitHub-Docs unter „GitHub Actions billing“.
Wo liegt die Workflow-Datei?
Immer im Ordner .github/workflows/ im Wurzelverzeichnis deines Repositorys. Jede .yml- oder .yaml-Datei dort ist ein eigener Workflow. Liegt sie woanders, ignoriert GitHub sie.
Warum startet mein Workflow nicht?
Die häufigsten Gründe: Die Datei liegt nicht in .github/workflows/, der Trigger passt nicht (etwa branches: [main], aber du pushst auf master), ein Pfadfilter schließt deine Änderung aus, oder die YAML-Datei ist ungültig. Im letzten Fall zeigt GitHub einen roten Lauf mit 0 Sekunden Dauer und dem Hinweis „workflow file issue“. Dann hilft actionlint.
Was ist der Unterschied zwischen Job und Step?
Ein Job läuft auf einer eigenen Maschine. Mehrere Jobs laufen standardmäßig parallel und teilen keine Dateien. Steps sind die einzelnen Schritte innerhalb eines Jobs, laufen nacheinander und teilen sich dasselbe Dateisystem.
Wie gebe ich Daten von einem Job an den nächsten weiter?
Kleine Werte über outputs des Jobs, Dateien über Artifacts: im ersten Job actions/upload-artifact, im zweiten Job (mit needs:) actions/download-artifact.
Sind Secrets in GitHub Actions sicher?
Secrets werden verschlüsselt gespeichert und im Log geschwärzt. In unserem Test wurden sie auch in Base64 erkannt, rückwärts geschrieben oder mit Leerzeichen dazwischen aber nicht. Behandle die Schwärzung als Sicherheitsnetz: Secrets nie ausgeben, Rechte des Tokens klein halten, Drittanbieter-Actions auf Commit-Hashes festnageln.
Was passiert, wenn ein Secret nicht existiert?
Nichts Sichtbares. Der Ausdruck ergibt einfach einen leeren String, der Schritt läuft weiter. Prüfe deshalb am Anfang kritischer Jobs mit [ -n "$VAR" ], ob das Secret gesetzt ist.
Welche Version von actions/checkout soll ich nehmen?
Die aktuelle Hauptversion. Am 16.11.2026 war das actions/checkout@v7. Ältere Versionen wie @v4 funktionieren noch, erzeugen aber eine Warnung, weil sie für Node.js 20 gebaut sind. Mit Dependabot bleibst du automatisch aktuell.
Kann ich GitHub Actions lokal testen?
Teilweise. Das Werkzeug act führt Workflows lokal in Docker-Containern aus. Die Umgebung weicht aber vom echten Runner ab, manche Actions verhalten sich anders. Für Syntaxfehler reicht oft schon actionlint. Für alles andere ist ein privates Test-Repository, wie wir es für diesen Artikel genutzt haben, der zuverlässigste Weg.
GitHub Actions oder GitLab CI, was ist besser?
Beide können im Kern dasselbe. Liegt dein Code auf GitHub, ist GitHub Actions die naheliegende Wahl, weil es ohne Einrichtung funktioniert und der Marketplace sehr viele fertige Actions bietet. GitLab CI ist stark, wenn du ohnehin GitLab nutzt oder es selbst hostest.
Wie lange darf ein Job laufen?
Standardmäßig bis zu 360 Minuten auf GitHub-gehosteten Runnern. Setze mit timeout-minutes einen deutlich kleineren Wert, damit ein hängender Job nicht stundenlang Kontingent verbraucht.
Fazit: Was ein gutes GitHub Actions Tutorial dir mitgeben sollte
GitHub Actions ist erstaunlich schnell eingerichtet. Eine Datei, ein Push, und 14 Sekunden später hast du Tests auf drei Node-Versionen. Genau das macht es aber auch leicht, Dinge zu übersehen. Die Fallen, die wir in unserem Test gefunden haben, werfen alle keine klare Fehlermeldung: kaputtes YAML zeigt nur einen generischen Hinweis, ein fehlendes Secret ist einfach leer, umgeformte Secrets landen im Klartext im Log, und veraltete Action-Versionen funktionieren mit einer Warnung, die niemand liest.
Unsere Empfehlung für den Einstieg: Kopiere den Workflow aus Schritt 1, setze permissions und timeout-minutes, lass actionlint mitlaufen und aktiviere Dependabot für Actions. Damit hast du in zehn Minuten eine CI, die mehr richtig macht als die meisten Workflows, die man in fremden Repos findet. Den Deploy baust du danach in Ruhe dazu, mit eigenem Schlüssel, known_hosts und einer environment-Freigabe.