GitHub Actions: Workflows und YAML

GitHub Actions ist heute das mit Abstand am weitesten verbreitete CI/CD-System – besonders für Open-Source-Projekte und kleinere bis mittlere Teams. Der Grund: es ist direkt in GitHub integriert, kostenlos für Public Repos und sehr einfach einzurichten. Eine YAML-Datei ins Repo und du hast eine CI-Pipeline.

Diese Lektion zeigt dir die GitHub-Actions-Syntax von Grund auf: Workflows, Jobs, Steps, Triggers, Marketplace-Actions, Secrets, Matrix-Builds. Am Ende kannst du eigene Pipelines schreiben. Die Konzepte sind oft ähnlich zu GitLab CI/CD (L4) – wer GitHub Actions kann, lernt GitLab schnell.

1) Die Grundstruktur

GitHub Actions basiert auf Workflows – YAML-Dateien im Verzeichnis .github/workflows/. Jeder Workflow ist eine eigene Pipeline. Du kannst beliebig viele Workflows in einem Repository haben, jeder mit eigenem Trigger und Zweck.

Wo liegen die Workflows?

Code Actions Issues Pull Requests

main-app

📁 main-app/

  📁 .github/

    📁 workflows/ ← hier kommen die YAML-Workflows hin

      📄 ci.yml

      📄 deploy.yml

      📄 nightly-tests.yml

  📁 src/

  📄 package.json

  📄 README.md

Der Pfad muss genau .github/workflows/ sein, sonst erkennt GitHub die Files nicht. Achte auf das Hidden-Folder-Punkt vorne. Die Dateiendung ist .yml oder .yaml, beides geht.

2) Anatomie eines Workflows

Ein Workflow hat einen klaren Aufbau. Schau dir die Hierarchie an – klick auf eine Zeile für Erklärung:

Workflow-Anatomie – klick die Elemente

name: CI Pipeline

on:

push:

branches: [main]

env:

NODE_VERSION: "20"

jobs:

test:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- run: npm test

name: Name des Workflows, wie er im GitHub-UI angezeigt wird. Optional aber empfohlen für Übersicht.

YAML ist sehr empfindlich was Einrückung angeht. Immer Spaces, niemals Tabs. Übliche Konvention: 2 Spaces pro Einrückungsstufe. Ein einziger falscher Space-Wert kann den Workflow brechen.

3) Trigger-Events im Detail

GitHub Actions kennt über 30 verschiedene Trigger-Events. Hier die wichtigsten – klick die Tabs:

Die wichtigsten Trigger-Events

push

pull_request

schedule

workflow_dispatch

release

on:
  push:
    branches: [main, develop]
    paths:
      - 'src/**'
      - '!**.md'
    tags:
      - 'v*'

Triggert bei Push auf main oder develop. Mit paths nur wenn Dateien im src/ geändert wurden – Markdown-Änderungen ignoriert (!**.md). Auch bei Tags mit Präfix „v" (Releases).

4) Marketplace: vorgefertigte Actions

Die wahre Stärke von GitHub Actions ist der Marketplace mit über 20.000 vorgefertigten Actions. Du kannst sie mit uses: einfach einbinden. Hier die wichtigsten:

Die meistgenutzten Marketplace-Actions

actions/checkout

Holt Code aus dem Repo. Erste Action jedes Workflows.

@v4

actions/setup-node

Installiert Node.js in spezifischer Version

@v4

actions/setup-python

Installiert Python in spezifischer Version

@v5

actions/setup-java

Installiert JDK in spezifischer Version (Temurin, Adopt, etc.)

@v4

actions/cache

Cache für Dependencies, Build-Artefakte etc.

@v4

actions/upload-artifact

Artefakt am Workflow-Ende speichern (Reports, Builds)

@v4

docker/build-push-action

Docker-Image bauen und in Registry pushen

@v5

aws-actions/configure-aws-credentials

AWS-Credentials konfigurieren für Deploy

@v4

Achte immer auf den Versions-Tag mit @v4. Ohne Tag kann sich das Verhalten unangekündigt ändern – brüchige Pipelines drohen. Best Practice: explizite Version pinnen, gelegentlich manuell updaten.

5) Komplettes Beispiel: Node.js-CI

Setzen wir alles zusammen in einem realistischen Beispiel für ein Node.js-Projekt:

.github/workflows/ci.ymlYAML

1name: CI
2
3on:
push:
  branches: [main]
pull_request:
  branches: [main]
8
9jobs:
test-and-build:
  runs-on: ubuntu-latest
  steps:
    - name: Checkout
      uses: actions/checkout@v4
15
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: "20"
        cache: npm
21
    - name: Install deps
      run: npm ci
24
    - name: Lint
      run: npm run lint
27
    - name: Test
      run: npm test -- --coverage
30
    - name: Build
      run: npm run build
33
    - name: Upload Build Artifact
      uses: actions/upload-artifact@v4
      with:
        name: build-output
        path: dist/

Sechs Steps: Checkout, Node setup mit Cache, install, lint, test, build, artifact upload. Bei jedem PR und jedem Push auf main läuft das. Wenn ein Step rot, bricht alles ab. So einfach kann CI sein.

6) Matrix-Builds: gegen mehrere Versionen testen

Eine besonders mächtige Funktion: Matrix-Builds. Du definierst eine Liste von Versionen und der gleiche Job läuft parallel gegen alle. Klassischer Use-Case: deine Library soll mit Node 18, 20 und 22 funktionieren – pro Version eine Test-Run:

matrix.ymlYAML

1jobs:
test:
  runs-on: ${{ matrix.os }}
  strategy:
    matrix:
      os: [ubuntu-latest, windows-latest, macos-latest]
      node-version: ["18", "20", "22"]
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
    - run: npm test

Das ergibt 3 × 3 = 9 parallele Jobs: Ubuntu+Node18, Ubuntu+Node20, Ubuntu+Node22, Windows+Node18, … Wenn einer fehlschlägt, weißt du sofort wo das Problem liegt. Sehr beliebt bei Open-Source-Libraries.

7) Secrets: Passwörter und API-Keys sicher

Pipelines brauchen oft sensible Daten – API-Keys, Passwörter, Deployment-Tokens. Diese gehören nie ins Workflow-File. Stattdessen: Secrets – verschlüsselte Variablen in den Repo-Einstellungen:

Secrets sicher verwenden

⚠ Niemals tun!

- run: aws s3 cp ... --access-key=AKIAIOSFODNN7EXAMPLE

Niemals Credentials direkt im YAML! Wer das Repo klont, hat deine Keys.

richtig.ymlYAML

1- name: Deploy to S3
env:
  AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
  AWS_SECRET: ${{ secrets.AWS_SECRET }}
run: aws s3 cp ...

Secrets werden im Repo unter Settings → Secrets and variables → Actions angelegt. Sie sind schreibgeschützt – du kannst sie nie wieder im Klartext sehen, nur überschreiben. Bei Logs werden sie automatisch ausgeblendet (durch ***) – auch wenn jemand versucht sie zu echoen.

8) Job-Abhängigkeiten mit needs

Standardmäßig laufen alle Jobs parallel. Mit needs: machst du Abhängigkeiten:

needs.ymlYAML

1jobs:
test:
  runs-on: ubuntu-latest
  steps: [...]
5
build:
  needs: test          # wartet auf test-Job
  runs-on: ubuntu-latest
  steps: [...]
10
deploy:
  needs: [test, build]   # wartet auf beide
  runs-on: ubuntu-latest
  if: github.ref == 'refs/heads/main'
  steps: [...]

Hier: test läuft zuerst, dann build, dann deploy. Aber: deploy läuft nur wenn der Branch main ist. Mit if: kannst du Conditional-Execution einbauen.

9) Self-hosted Runners

GitHub stellt kostenlose Runner (ubuntu-latest, windows-latest, macos-latest), aber für mehr Kontrolle kannst du eigene Runner betreiben:

Vorteile: viel schneller (eigene Hardware), Zugriff auf internes Netzwerk, eigene Tools vorinstalliert, günstiger bei viel Volumen
Nachteile: Wartungsaufwand, Sicherheits-Verantwortung, eigene Hardware nötig
Setup: Repo → Settings → Actions → Runners → New Runner. GitHub liefert ein Skript zum Installieren.
YAML: runs-on: self-hosted statt ubuntu-latest

Für mittlere bis große Unternehmen ist self-hosted Standard. Für kleine Teams reichen die kostenlosen GitHub-Runner meist locker aus.

10) Praktische Tipps

Was du bei der Arbeit mit GitHub Actions wissen solltest:

YAML-Validator nutzen: VS Code mit YAML-Extension warnt vor Fehlern, bevor du committest
Workflow-Datei klein halten: bei mehr als 100 Zeilen aufteilen in mehrere Workflows oder Reusable Workflows
Limits beachten: GitHub gibt kostenlos 2000 Minuten/Monat für Privat-Repos, mehr kostet
Concurrency-Group: concurrency: verhindert dass mehrere Workflow-Instanzen sich gegenseitig stören
Composite Actions: eigene wiederverwendbare Actions für komplexe Schritte
act: Tool zum lokalen Testen von GitHub Actions vor dem Push
Status-Badges: README mit Badge wie ![CI](https://github.com/.../workflows/CI/badge.svg)

Zusammenfassung

GitHub Actions ist heute der Marktführer für CI/CD bei Open Source und kleineren Teams. Workflows liegen in .github/workflows/ als YAML. Hierarchie: Workflow → Jobs → Steps. Trigger: push, pull_request, schedule, workflow_dispatch, release. Marketplace: über 20.000 vorgefertigte Actions (actions/checkout, actions/setup-node, …) – mit Versions-Tag pinnen. Matrix-Builds: gleicher Job parallel gegen mehrere OS/Versionen. Secrets: verschlüsselte Variablen in Repo-Settings, niemals im YAML hardcoden. needs: für Job-Abhängigkeiten, if: für Conditional Execution. Kostenlose Runner reichen für die meisten Projekte; self-hosted für Enterprise. Limits: 2000 Min/Monat gratis bei Private Repos. Pflichtwissen für moderne Entwicklung.