GitHub Actions Einstieg: YAML-Workflow-Grundlagen und Trigger-Konfiguration

Der rote Fehler auf dem Bildschirm ist so grell, dass man am liebsten die Tastatur durch die Wand werfen würde.

Der Code läuft lokal einwandfrei – sobald Sie zu GitHub pushen, bricht alles zusammen. Die YAML-Datei haben Sie sechsmal geändert, jedes Mal wegen Einrückungsproblemen. Warum ist das schwieriger als Programmieren?

GitHub Actions selbst ist gar nicht so kompliziert. Schwierig sind die Dokumente: Hunderte Seiten Konfigurationsreferenz auf einmal – da wird einem schwindelig. Dieser Artikel erklärt die Kernstruktur eines YAML-Workflows auf die einfachste Art.

Sie lernen:

• Die vier Kernfelder einer YAML-Datei und ihre konkrete Funktion
• Konfiguration und Einsatzszenarien von 8 gängigen Triggern
• Eine vollständige Workflow-Vorlage zum direkten Kopieren
• Fallen, in die ich selbst getappt bin – und wie Sie sie vermeiden

Bereit? Dann legen wir los.

YAML-Workflow-Datei: vier Kernfelder

Ehrlich gesagt: Als ich GitHub Actions zum ersten Mal sah, wirkten die YAML-Dateien unter .github/workflows wie Hieroglyphen. Einrückungen, Doppelpunkte – ein falsches Leerzeichen, und alles bricht.

Später wurde klar: Es gibt eigentlich nur vier Kernbereiche. Verstehen Sie diese, ist der Rest optional.

name: Dem Workflow einen Namen geben

Das einfachste Feld – und doch übersehen es viele (ich eingeschlossen) am Anfang.

name: CI for Node.js App

name ist der Titel, den Sie auf der GitHub-Actions-Seite sehen. Nach dem Push öffnen Sie den Actions-Tab im Repository – genau diese Zeile steht dort.

Ein Tipp: Projektname + Funktionsbeschreibung. Zum Beispiel MyApp CI oder Backend Deploy. Bei vielen Workflows finden Sie sofort den richtigen.

Das Feld ist optional. Fehlt es, nutzt GitHub den Dateinamen. Ich rate davon ab – Dateinamen sind oft Abkürzungen und wenig aussagekräftig.

on: Wann auslösen

on ist der „Schalter“ des Workflows. Sie sagen GitHub, unter welchen Bedingungen er laufen soll.

Die einfachste Form:

on: push

Bedeutung: Bei jedem Push wird ausgelöst.

In echten Projekten brauchen Sie meist feinere Steuerung – zum Beispiel nur bei Push auf main:

on:
  push:
    branches: [main]

Oder zusätzlich bei Pull Requests:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

Trigger sind das Herzstück von GitHub Actions; einen ganzen Abschnitt widmen wir 8 gängigen Szenarien. Merken Sie sich: on legt den Auslösezeitpunkt fest.

jobs: Was erledigt werden soll

jobs ist der Hauptteil – hier definieren Sie konkrete Aufgaben.

Ein Workflow kann mehrere Jobs enthalten; standardmäßig laufen sie parallel. Jeder Job braucht eine Laufzeitumgebung über runs-on:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # ... Schrittliste

Obiger Code definiert einen Job build, der auf der neuesten Ubuntu-Version von GitHub läuft.

Bei mehreren Jobs steuern Sie Abhängigkeiten mit needs:

jobs:
  test:
    runs-on: ubuntu-latest
    # ... Testschritte

  deploy:
    needs: test  # wartet, bis test fertig ist
    runs-on: ubuntu-latest
    # ... Deploy-Schritte

deploy startet erst nach test. Schlägt test fehl, läuft deploy nicht.

steps: Konkrete Ausführungsschritte

steps sind die kleinsten Einheiten innerhalb eines Jobs – Befehle oder Actions nacheinander.

Zwei Schreibweisen:

1. Befehle mit run:

steps:
  - name: Install dependencies
    run: npm ci

  - name: Run tests
    run: npm test

Hinter run steht der Terminalbefehl – wie lokal.

2. Actions mit uses aufrufen:

steps:
  - name: Checkout code
    uses: actions/checkout@v4

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'

uses ist der Trumpf von GitHub Actions: fertige Actions anderer nutzen. actions/checkout@v4 checkt den Code aus, actions/setup-node@v4 richtet Node.js ein.

with übergibt Parameter – node-version: '20' bedeutet: Node.js 20 verwenden.

Vier Felder – einfacher als gedacht?

Trigger im Detail: 8 gängige Szenarien

Wie erwähnt legt on den Zeitpunkt fest. GitHub Actions kennt Dutzende Trigger; in der Praxis reichen wenige.

Eine Übersichtstabelle:

Trigger	Typisches Szenario	Konfigurationsbeispiel
push	Code-Push auf Branch	on: push: branches: [main]
pull_request	PR erstellt oder aktualisiert	on: pull_request: types: [opened, synchronize]
schedule	Zeitgesteuert (Cron)	on: schedule: - cron: '0 0 * * *'
workflow_dispatch	Manuell	on: workflow_dispatch: inputs: env: ...
workflow_call	Wiederverwendbarer Workflow	on: workflow_call: inputs: ...
release	Release-Event	on: release: types: [published]
issues	Issue-Event	on: issues: types: [opened, labeled]
repository_dispatch	Externes Event	on: repository_dispatch: types: [deploy]

Die wichtigsten im Detail:

push: Der Basis-Trigger

push ist meist der erste Trigger – ausgelöst bei Push auf einen Branch.

Einfache Konfiguration:

on: push

Problem: Jeder Push auf jedem Branch löst aus. Bei 20 Branches und vielen Entwicklern verbrauchen Sie schnell das Free-Kontingent.

Sinnvoller: Branches einschränken:

on:
  push:
    branches: [main, develop]

Oder mit Wildcards:

on:
  push:
    branches:
      - 'main'
      - 'release/**'  # passt auf release/v1.0, release/v2.0 usw.

pull_request: Wächter vor dem Merge

pull_request löst bei Erstellung oder Update eines PR aus – typisch für Tests und Linting.

on:
  pull_request:
    branches: [main]

Mit types feiner steuern:

on:
  pull_request:
    types: [opened, synchronize, reopened]

• opened: PR neu erstellt
• synchronize: neuer Commit im PR
• reopened: PR wieder geöffnet

So laufen Workflows nur in diesen Fällen – weniger verschwendete Minuten.

schedule: Zeitgesteuerte Jobs

schedule nutzt Cron-Ausdrücke – z. B. täglich um Mitternacht testen:

on:
  schedule:
    - cron: '0 0 * * *'  # täglich UTC 0 Uhr

Cron hat 5 Felder: Minute, Stunde, Tag, Monat, Wochentag.

Häufige Zeiten:

• 0 0 * * *: täglich UTC 0 Uhr (8 Uhr morgens Peking / 1 Uhr nachts MEZ im Winter)
• 0 */6 * * *: alle 6 Stunden
• 30 2 * * 1: montags UTC 2:30

Achtung: GitHub nutzt UTC. Für 9 Uhr morgens Peking-Zeit setzen Sie UTC 1 Uhr (0 1 * * *).

workflow_dispatch: Manuell starten

Manchmal soll nicht automatisch, sondern per Klick laufen – dafür ist workflow_dispatch da.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment-Umgebung'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

Danach erscheint auf der Actions-Seite „Run workflow“ – mit wählbaren Parametern.

Besonders praktisch beim Deploy: Tests automatisch, Deploy manuell.

workflow_call: Workflows wiederverwenden

Bei komplexer Logik oder gleichem Ablauf in mehreren Repositories wird ein Workflow über workflow_call wiederverwendbar.

Wiederverwendbaren Workflow definieren:

# .github/workflows/ci.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm test

In einem anderen Workflow aufrufen:

# .github/workflows/main.yml
on: push

jobs:
  call-ci:
    uses: ./.github/workflows/ci.yml
    with:
      node-version: '20'

Eine CI-Logik, überall gleich – Änderung an einer Stelle, überall wirksam.

Die übrigen Trigger (release, issues, repository_dispatch) sind seltener – Details in der GitHub-Dokumentation.

Praxis: Ihre erste Workflow-Vorlage

Genug Theorie – probieren wir es aus.

Vollständiger CI-Workflow für ein Node.js-Projekt – direkt kopierbar:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # 1. Code auschecken
      - name: Checkout code
        uses: actions/checkout@v4

      # 2. Node.js einrichten
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      # 3. Abhängigkeiten installieren
      - name: Install dependencies
        run: npm ci

      # 4. Tests ausführen
      - name: Run tests
        run: npm test

So geht’s

Schritt 1: Im Projektroot .github/workflows anlegen (falls noch nicht vorhanden).

Schritt 2: Darin ci.yml erstellen und obigen Code einfügen.

Schritt 3: Committen und zu GitHub pushen.

Danach im Actions-Tab sollte der Workflow laufen.

Zeile für Zeile

• name: CI – Name auf der Actions-Seite
• on: push: branches: [main] – Push auf main löst aus
• on: pull_request: branches: [main] – PR gegen main ebenfalls
• jobs: build: – Job mit ID build
• runs-on: ubuntu-latest – neuestes Ubuntu von GitHub
• actions/checkout@v4 – Code auf die VM holen
• actions/setup-node@v4 – Node.js konfigurieren
• npm ci – Abhängigkeiten (schneller und reproduzierbarer als npm install)
• npm test – Tests starten

Kein Node.js-Projekt? Mittlere Schritte anpassen – z. B. Python:

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: '3.11'
  - run: pip install -r requirements.txt
  - run: pytest

Muster: Code holen → Umgebung → Dependencies → Tests.

Häufige Konfigurationsfehler

Fallen, in die ich getappt bin – damit Sie es nicht müssen.

Checkliste zum Abgleichen:

Fehlersymptom	Mögliche Ursache	Lösung
Workflow startet nicht	Branch-Filter falsch	branches prüfen, Groß-/Kleinschreibung beachten
YAML-Parse-Fehler	Tab-Einrückung	Nur Leerzeichen, kein Tab
Secrets wirken nicht	Falscher Scope	Secrets auf Job- oder Step-Ebene setzen
Job-Abhängigkeit scheitert	needs falsch	job-id exakt schreiben, case-sensitive
Workflow sehr langsam	Kein Cache	actions/cache für Dependencies
Berechtigungsfehler	GITHUB_TOKEN zu schwach	permissions im Job setzen

Fehler 1: Falsche Einrückung

Der häufigste Fehler – ohne Wettbewerb.

YAML reagiert empfindlich auf Einrückung: Leerzeichen, kein Tab. Pro Ebene in GitHub Actions üblicherweise 2 Leerzeichen.

# Falsch: Einrückung durcheinander
jobs:
  build:
  runs-on: ubuntu-latest  # sollte 4 Leerzeichen haben

# Richtig
jobs:
  build:
    runs-on: ubuntu-latest  # 4 Leerzeichen

In VS Code oder WebStorm: „Tab fügt Leerzeichen ein“ aktivieren – spart Ärger.

Fehler 2: Falscher Branch-Name

Branch-Namen sind case-sensitive. main und Main sind verschiedene Branches.

# Branch heißt main
on:
  push:
    branches: [Main]  # falsch – löst nicht aus

# Richtig
on:
  push:
    branches: [main]

Unsicher? Auf GitHub im Repository nachsehen oder lokal git branch ausführen.

Fehler 3: job-id falsch geschrieben

Bei mehreren Jobs mit Abhängigkeit muss needs die job-id exakt treffen.

jobs:
  test:
    runs-on: ubuntu-latest
    # ...

  deploy:
    needs: Test  # falsch – Großschreibung passt nicht
    runs-on: ubuntu-latest

# Richtig
jobs:
  test:
    runs-on: ubuntu-latest

  deploy:
    needs: test  # klein, wie oben
    runs-on: ubuntu-latest

Fehler 4: Secrets auf falscher Ebene

GitHub Secrets gibt es auf Repository- und Environment-Ebene. Referenz: ${{ secrets.XXX }}.

# Falsch: secrets ohne ${{ }}
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      API_KEY: secrets.MY_KEY

# Richtig
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      API_KEY: ${{ secrets.MY_KEY }}

Secrets sind verschlüsselt – im Log sehen Sie den Wert nicht. Prüfen, ob gesetzt:

- name: Debug
  run: echo "API_KEY is set: ${{ secrets.MY_KEY != '' }}"

Kein Leak des Keys, aber Sie sehen, ob er leer ist.

GitHub Actions vs. andere CI/CD-Tools

Vielleicht kennen Sie Jenkins, GitLab CI oder CircleCI. Wie schlägt sich GitHub Actions?

Vergleichstabelle:

Kriterium	GitHub Actions	GitLab CI	Jenkins	CircleCI
Konfiguration	YAML	YAML	Groovy	YAML
Hosting	Cloud-nativ	Cloud/Self-hosted	Self-hosted	Cloud-nativ
Integration	GitHub nativ	GitLab nativ	Konfiguration nötig	Konfiguration nötig
Lernkurve	Niedrig	Niedrig	Hoch	Mittel
Free-Kontingent	2.000 Min./Monat (privat)	400 Min./Monat	Unbegrenzt (self-hosted)	6.000 Min./Monat
Public Repos	Unbegrenzt	Unbegrenzt	Unbegrenzt	Unbegrenzt

Vorteile von GitHub Actions

1. Nahtlose Integration

Code liegt schon auf GitHub? GitHub Actions ist der naheliegendste Weg. Kein Webhook-Setup, kein eigener Server, keine Plugins. YAML-Datei anlegen, pushen, fertig.

2. Marketplace-Ökosystem

Tausende Actions im GitHub Marketplace – AWS, Azure, Google Cloud mit offiziellen Actions. Was Sie brauchen, existiert oft schon – per uses einbinden.

3. Free-Kontingent für Einzelentwickler

Public Repos unbegrenzt, private 2.000 Minuten monatlich – für persönliche Projekte und kleine Teams meist ausreichend.

Wann eher nicht GitHub Actions?

1. Code liegt nicht auf GitHub

GitLab oder Bitbucket? Nutzen Sie deren CI/CD. GitHub Actions per Webhook geht, ist aber umständlicher als die native Lösung.

2. Volle Kontrolle über die Laufzeitumgebung

Runner sind fest (Ubuntu/Windows/macOS) – eigene Software oder Spezial-Setup schwer. Jenkins mit self-hosted Runner ist flexibler.

3. Extreme Sicherheitsanforderungen

GitHub-hosted Runner sind VMs von GitHub. Bei hochsensiblen Projekten evtl. eigene CI – oder Kompromiss: self-hosted Runner.

Meine Empfehlung

Für die meisten Einzelentwickler und kleinen Teams:

• Code auf GitHub → GitHub Actions
• Code auf GitLab → GitLab CI
• Hohe Individualisierung → Jenkins oder self-hosted Runner

Kein absolut bestes Tool – das Passende für Ihr Setup zählt.

Fazit

Damit wissen Sie, wie YAML-Workflows in GitHub Actions funktionieren.

Kernpunkte:

• Vier Felder: name, on, jobs, steps
• Acht Trigger – am meisten: push, pull_request, schedule
• Kopierbare Vorlage: Code holen → Umgebung → Dependencies → Tests
• Vier Fallen: Einrückung, Branch-Name, job-id, Secrets

Als Nächstes:

1. Ersten Workflow im eigenen Projekt anlegen (Vorlage aus diesem Artikel anpassen)
2. Fortgeschrittenen Artikel der Serie lesen: „GitHub Actions Cache-Strategie: CI/CD-Pipeline 5× beschleunigen“
3. GitHub Marketplace durchstöbern – fertige Actions entdecken

Wer einmal Automatisierung schmeckt, will selten zurück.