GitHub Actions lokal testen mit Act

act ist ein Open-Source-CLI-Tool von nektos, mit dem du GitHub Actions direkt lokal auf deinem Rechner ausführen kannst – ganz ohne Commit & Push. Es emuliert GitHub-Actions-Umgebungen mit Docker-Containern, verwendet dieselben Umgebungsvariablen und Dateisystem-Zugriffe wie GitHub selbst.

Installation auf deinem System

Als Voraussetzung muss zunächst Docker installiert sind. Dafür reicht es aus Docker Desktop unter Windows bzw. Mac und die Docker Engine unter Linux zu installieren.

Danach könnt ihr je nach Plattform das Tool installieren.

macOS: brew install act

Windows: winget install --id=nektos.act

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

Grundbefehle & Konfiguration

Nach dem ersten act-Aufruf wirst du nach einem Docker-Image gefragt. Hierbei stehen drei Varianten zur Auswahl: Micro, Medium und Large. Für die meisten Anwendungsfälle sollte das Medium-Image mit etwa 500 MB ausreichen.

act               # Führt alle push-basierten Workflows aus
act pull_request  # Simuliert ein pull_request-Event
act -l            # Listet alle verfügbaren Workflows/Jobs auf
act -j JOBNAME    # Führt nur den Job JOBNAME aus

act               # Führt alle push-basierten Workflows aus
act pull_request  # Simuliert ein pull_request-Event
act -l            # Listet alle verfügbaren Workflows/Jobs auf
act -j JOBNAME    # Führt nur den Job JOBNAME aus

Für die gezielte Ausführung eines bestimmten Workflows, könnt ihr den folgenden Command benutzen:

act -W '.github/workflows/meine-yaml-datei.yml'

act -W '.github/workflows/meine-yaml-datei.yml'

Solltet ihr Variablen und Secrets in eurer Pipeline verwenden, so könnt ihr diese in Dateien, wie .secrets oder .vars speichern und an den act-Aufruf anfügen.

act --secret-file .secrets --var-file .vars

act --secret-file .secrets --var-file .vars

Beispiel-Ausführung

Nehmen wir als Beispiel doch mein GitHub-Repo tsjdev-apps/podcastr-console. Dieses beinhaltet bereits einen CI-Workflow im Ordner .github/workflows. Über den Command act -l können wir uns alle definierten Workflows einmal auflisten.

Nun können wir unseren Workflow mit dem Aufruf von act starten.

Hierbei handelt es sich um einen recht simplen Workflow, der einfach nur die Packages wiederherstellt und anschließend ein dotnet build aufruft, aber es verdeutlicht das Arbeiten mit act. Es muss bei der Erstellung einer GitHub Action diese nun nicht jedes Mal gepusht werden, sondern man kann die GitHub Action lokal entwickeln und testen und das fertige Ergebnis dann erst veröffentlichen.

Typische Use-Cases

• Workflow-Anpassungen prüfen, ohne Commit-Historie zu verstopfen.
• Fehler in Scripts, Actions oder Step-Konfiguration sofort erkennen.
• Schnelles Testen von Pull-Request-Triggern mittels act pull_request.
• Nutzung von externen Actions lokal, z. B. actions/checkout, setup-dotnet etc.
• Variables & Secrets testen – wie vars.APP_ID oder secrets.MY_VAR

Fazit

Mit act machst du CI/CD günstig & schnell auf deinem lokalen Rechner testbar: Schnelle Rückmeldung ohne Push. Bessere Kontrolle über Workflows, Secrets & Umgebungen. Geringere Abhängigkeit von GitHub-Umgebung bei Entwicklung.