Was ist Act?

Act ist ein Open-Source-Command-Line-Tool, mit dem du GitHub Actions Workflows lokal ausführen kannst. Du testest und debuggst CI/CD-Pipelines, ohne Code zu GitHub pushen zu müssen.

Für Entwickler, die häufig GitHub Actions schreiben, ist dies ein Produktivitäts-Booster:

  • Schnelle Iteration: Workflow-Änderungen sofort lokal testen, keine Wartezeit durch GitHub-Warteschlangen
  • Ressourcen sparen: Keine GitHub Actions-Minuten verbrauchen (besonders bei privaten Repositories)
  • Offline-Debugging: Workflows auch ohne Internetverbindung testen
  • Sicherheitstests: Workflows in isolierter Umgebung auf Sicherheit prüfen, unbeabsichtigte gefährliche Operationen vermeiden

Warum braucht man Act?

GitHub Actions ist eine leistungsstarke CI/CD-Plattform, aber das Debuggen von Workflows hat einen Schwachpunkt:

.github/workflows/test.yml ändern 
→ git commit 
→ git push 
→ Auf GitHub-Warteschlange warten (Minuten bis Stunden möglich)
→ Logs prüfen, Fehler entdecken
→ Schritte wiederholen

Dieser Zyklus ist sehr zeitaufwendig. Mit Act wird daraus:

.github/workflows/test.yml ändern 
→ act -j test    # Sofort lokal ausführen
→ Ausgabe prüfen, Problem beheben
→ Erneut ausführen, erst nach Bestätigung pushen

Die Effizienz steigt um mindestens das Zehnfache.

Act im Vergleich zu anderen Lösungen

Feature Act GitHub Web-UI Docker Compose-Simulation
Ausführungsgeschwindigkeit ⚡ Lokal sofort 🐌 Warteschlange erforderlich ⚡ Lokal, aber komplexe Konfiguration
Authentizität ✅ Echte GitHub Actions Runner-Images ✅ Vollständig echt ❌ Manuelle Simulation nötig
Kosten 💰 Kostenlos (lokal) 💰 Verbraucht Actions-Minuten 💰 Kostenlos
Benutzerfreundlichkeit ✅ Ein Befehl ✅ Grafische Oberfläche ❌ Aufwendige Konfiguration
Offline-Support ✅ Vollständig offline ❌ Netzwerk erforderlich ✅ Offline möglich

Act installieren

macOS (Homebrew)

BASH 
brew install act

Linux

Ubuntu/Debian:

BASH 
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Arch Linux:

BASH 
yay -S act
# oder
paru -S act

Windows

Chocolatey:

POWERSHELL 
choco install act-cli

Scoop:

POWERSHELL 
scoop install act

Installation überprüfen

BASH 
act --version
# Ausgabe ähnlich: act version 0.2.x

Schnellstart: Ersten Workflow ausführen

Voraussetzungen

Stelle sicher, dass dein Projekt-Root-Verzeichnis ein .github/workflows/-Verzeichnis enthält, das mindestens eine Workflow-Datei (.yml oder .yaml) beinhaltet.

Verfügbare Workflows auflisten

BASH 
cd /path/to/your/project
act -l

Beispielausgabe:

Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      test    Test      CI             ci.yml         push,pull_request
0      build   Build     CI             ci.yml         push,pull_request

Bestimmten Job ausführen

BASH 
# Job mit Namen "test" ausführen
act -j test

# Alle Jobs ausführen
act

# Workflow für bestimmtes Event ausführen (z.B. pull_request)
act pull_request

Hinweise zur ersten Ausführung

Beim ersten Mal lädt Act die erforderlichen Docker-Images herunter (normalerweise catthehacker/ubuntu:act-latest). Das kann einige Minuten dauern. Bei späteren Ausführungen wird der Cache genutzt, was schneller geht.

INFO[0000] Using docker host 'unix:///var/run/docker.sock'
INFO[0000] Pulling image 'catthehacker/ubuntu:act-latest'
...

Fortgeschrittene Nutzung

1. Verschiedene Runner-Images verwenden

Act verwendet standardmäßig Ubuntu-Images. Mit dem -P-Parameter kannst du jedoch verschiedene Plattformen angeben:

BASH 
# Ubuntu 22.04 verwenden
act -P ubuntu-latest=catthehacker/ubuntu:act-22.04

# Ubuntu 20.04 verwenden
act -P ubuntu-latest=catthehacker/ubuntu:act-20.04

# Leichtgewichtiges Image verwenden (schneller, aber eingeschränkte Funktionen)
act -P ubuntu-latest=node:16-buster-slim

2. Secrets und Umgebungsvariablen übergeben

Viele Workflows benötigen Secrets (wie API-Keys, Tokens). Du kannst diese über .env-Dateien oder die Kommandozeile übergeben:

Methode 1: .env-Datei verwenden

Erstelle im Projekt-Root eine .env-Datei:

BASH 
MY_API_KEY=dein_geheimer_schluessel
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Dann ausführen:

BASH 
act --secret-file .env

Methode 2: Direkt über Kommandozeile

BASH 
act -s MY_API_KEY=dein_geheimer_schluessel -s GITHUB_TOKEN=ghp_xxxxxxxxxxxx

3. Mehrere Jobs parallel ausführen

Wenn dein Workflow mehrere unabhängige Jobs hat, kannst du --parallel zur Beschleunigung nutzen:

BASH 
act --parallel

4. Dry-Run-Modus

Nur die auszuführenden Schritte anzeigen, nicht tatsächlich ausführen:

BASH 
act -n

5. Benutzerdefiniertes Arbeitsverzeichnis

Wenn der Workflow eine bestimmte Verzeichnisstruktur benötigt, kannst du Bind-Mounts verwenden:

BASH 
act --bind

Dadurch wird das aktuelle Verzeichnis in den Container gemountet, sodass Dateiänderungen sofort wirksam werden.

Praxisbeispiele

Beispiel 1: CI für Node.js-Projekt debuggen

Angenommen, du hast ein Node.js-Projekt mit folgendem Workflow:

YAML 
# .github/workflows/nodejs.yml
name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

Lokal ausführen:

BASH 
act -j test

Wenn Tests fehlschlagen, zeigt Act die vollständige Log-Ausgabe an, was die Fehlersuche erleichtert.

Beispiel 2: Python-Matrix mit mehreren Versionen testen

YAML 
# .github/workflows/python.yml
name: Python Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests
        run: pytest

Tests für alle Python-Versionen ausführen:

BASH 
act -j test

Act durchläuft automatisch alle Kombinationen der Matrix und führt sie nacheinander aus.

Beispiel 3: Docker-Build debuggen

YAML 
# .github/workflows/docker.yml
name: Build Docker Image

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Run tests in container
        run: docker run myapp:${{ github.sha }} npm test

Vor der lokalen Ausführung sicherstellen, dass der Docker-Daemon läuft:

BASH 
# Prüfen, ob Docker verfügbar ist
docker info

# Workflow ausführen
act -j build

Häufige Probleme und Lösungen

Problem 1: Berechtigungsfehler

Symptom: permission denied while trying to connect to the Docker daemon socket

Lösung:

BASH 
# Aktuellen Benutzer zur docker-Gruppe hinzufügen
sudo usermod -aG docker $USER
# Neu anmelden oder newgrp docker ausführen

Alternativ Act mit sudo ausführen (nicht empfohlen):

BASH 
sudo act

Problem 2: Nicht genug Speicher

Symptom: OOM (Out of Memory) bei großen Workflows

Lösung: Anzahl paralleler Jobs begrenzen

BASH 
act --max-parallel 1

Problem 3: Action nicht gefunden

Symptom: unable to find action 'actions/checkout@v4'

Lösung: Act muss Actions von GitHub herunterladen. Stelle sicher, dass die Netzwerkverbindung funktioniert. Für private Actions muss GITHUB_TOKEN gesetzt sein.

Problem 4: Umgebungsvariablen wirken nicht

Symptom: Im Workflow referenzierte Umgebungsvariablen sind leer

Lösung: Stelle sicher, dass Variablen korrekt über --secret-file oder -s übergeben wurden und im Workflow mit ${{ env.VAR_NAME }} oder ${{ secrets.VAR_NAME }} referenziert werden.

Best Practices

  1. Immer lokal testen vor dem Push: Gewöhne dir an, Workflows nach Änderungen zuerst mit Act zu validieren
  2. .env-Datei für Secret-Management verwenden: Keine sensiblen Informationen hardcoden, .env zu .gitignore hinzufügen
  3. Act regelmäßig aktualisieren: brew upgrade act oder neueste Version neu installieren
  4. Mit VS Code kombinieren: GitHub Actions-Erweiterung installieren, Workflows direkt im Editor vorschauen
  5. Act als optionalen Schritt in CI behalten: In PR-TemplatesContributors an lokale Tests erinnern

Fazit

Act ist ein unverzichtbares Tool für GitHub Actions-Entwickler. Es verkürzt den ursprünglich minuten- oder stundenlangen Debug-Zyklus auf wenige Sekunden. Egal ob einfache Unit-Test-Workflows oder komplexe mehrstufige Deployment-Pipelines – Act ermöglicht schnelle lokale Validierung.

Kernvorteile im Überblick: - ⚡ Schnelle Iteration: Lokal sofort ausführen, keine GitHub-Warteschlangen - 💰 Kosten sparen: Keine GitHub Actions-Minuten verbrauchen - 🔒 Sichere Isolation: Läuft im Container, beeinflusst Host-Umgebung nicht - 🛠️ Echte Umgebung: Verwendet dieselben Runner-Images wie GitHub, zuverlässige Ergebnisse

Wenn du häufig GitHub Actions-Workflows schreibst oder wartest, empfehlen wir dringend, Act in deine Toolbox aufzunehmen.

Weiterführende Links: - Act GitHub-Repository - Act offizielle Dokumentation - GitHub Actions Dokumentation