GitHub Actions Runner-Konfiguration

Actionforge ermoeglicht dir, GitHub Actions Workflow-Graphs auf deiner Maschine zu debuggen, Workflow-Bugs zu eliminieren und GitHub-Runner-Kosten zu reduzieren. Wenn actrun einen GitHub Actions Workflow-Graph erkennt (d.h. einen Graph, der aus dem GitHub Actions Workflow-Template erstellt wurde), richtet es automatisch eine simulierte GitHub Actions-Umgebung ein, sodass du deine Workflows lokal testen kannst, bevor du auf GitHub pushst.

Debug Session einrichten

Wenn du eine Debug Session fuer einen GitHub Actions Workflow-Graph startest, enthaelt der Einrichtungsdialog zusaetzliche GitHub Actions-spezifische Felder:

1. Runner herunterladen — Lade den Actionforge Runner herunter fuer deine Plattform.
2. Lokalen Repository-Pfad festlegen — Gib den lokalen Pfad zu deinem geklonten GitHub Repository ein. Er wird als GITHUB_WORKSPACE verwendet.
3. GitHub Token festlegen — Erstelle einen Fine-grained Personal Access Token mit minimalen Berechtigungen. Der Token ist Ende-zu-Ende-verschluesselt und kann nur von deinem lokalen Runner entschluesselt werden.
4. Session Token kopieren — Kopiere den Session Token und fuege ihn in deinen lokalen Runner ein, um dich zu verbinden.

Der Dialog konfiguriert die Umgebung fuer dich — keine manuelle Konfiguration von Umgebungsvariablen noetig bei Debug Sessions.

---

CLI-Konfiguration (ohne Debug Session)

Wenn du deinen GitHub Actions Workflow-Graph lieber direkt ueber die Kommandozeile ausfuehren moechtest, folge diesen Schritten:

1. actrun herunterladen und installieren

Lade den Runner CLI actrun fuer deine Plattform herunter und installiere ihn.

actrun herunterladen

Fuer detaillierte Installationsanweisungen schau dir den Installations-Guide an.

2. GitHub Access Token erstellen

Viele GitHub Actions benoetigen einen GITHUB_TOKEN, um sich bei der GitHub API zu authentifizieren. Um diese Actions lokal auszufuehren, erstelle einen Fine-grained Personal Access Token:

1. Klicke auf Generate new token
2. Gib ihm einen beschreibenden Namen (z.B. “actrun local development”)
3. Setze ein Ablaufdatum
4. Waehle die Repositories aus, auf die du zugreifen moechtest
5. Unter Repository permissions erteile die Berechtigungen, die deine Actions benoetigen. Sofern du keine spezifischen GitHub API-Features brauchst, belasse die Standardberechtigungen, die read-Zugriff auf oeffentliche Ressourcen geben.
6. Klicke auf Generate token und kopiere den Token

Setze den Token als Umgebungsvariable, bevor du actrun ausfuehrst:

macOS / Linux

export ACT_INPUT_TOKEN="ghp_your_token_here"

Windows

PowerShell

$env:ACT_INPUT_TOKEN = "ghp_your_token_here"

Command Prompt

set ACT_INPUT_TOKEN=ghp_your_token_here

Halte deinen Token sicher

Committe deinen Token niemals in die Versionsverwaltung. Erwaege die Verwendung einer .actconfig-Datei (zur .gitignore hinzugefuegt) oder des --env-file-Flags mit einer .env-Datei.

3. Erforderliche Umgebungsvariablen setzen

Navigiere zum Root deines Repositories und setze die folgenden Umgebungsvariablen:

macOS / Linux

cd /path/to/your/repo
export GITHUB_WORKSPACE="$(pwd)"
export GITHUB_EVENT_NAME="push"

Windows

PowerShell

cd C:\path\to\your\repo
$env:GITHUB_WORKSPACE = (Get-Location).Path
$env:GITHUB_EVENT_NAME = "push"

Command Prompt

cd C:\path\to\your\repo
set GITHUB_WORKSPACE=%CD%
set GITHUB_EVENT_NAME=push

Variable	Beschreibung
GITHUB_WORKSPACE	Pfad zum Root deines Git-Repositories. actrun nutzt ihn zur Erkennung von Repository-Name, Branch und Commit.
GITHUB_EVENT_NAME	Das Event, das den Workflow ausgeloest hat (z.B. push, pull_request, workflow_dispatch).

4. actrun ausfuehren

actrun my_workflow.act

---

Automatische Umgebungskonfiguration

Wenn actrun einen GitHub Actions Workflow-Graph erkennt, der ausserhalb von GitHub Actions ausgefuehrt wird, konfiguriert es automatisch die folgenden Umgebungsvariablen basierend auf deinem Git-Repository:

Variable	Wert	Beschreibung
CI	true	Zeigt eine CI-Umgebung an
GITHUB_ACTIONS	true	Zeigt eine GitHub Actions-Umgebung an
GITHUB_REPOSITORY	owner/repo	Abgeleitet vom Git-Remote origin
GITHUB_REF	refs/heads/branch	Aktuelle Git-Branch-Referenz
GITHUB_REF_NAME	branch	Aktueller Branch-Name
GITHUB_SHA	Commit Hash	Aktueller HEAD-Commit
RUNNER_OS	macOS / Linux / Windows	Erkanntes Betriebssystem
RUNNER_ARCH	X64 / ARM64	Erkannte CPU-Architektur
RUNNER_TEMP	Temp-Verzeichnis	Temporaerer Speicher fuer Actions
RUNNER_TOOL_CACHE	~/.actrun/tool-cache	Wo Actions Tools cachen

Die folgenden Dateien fuer die Kommunikation zwischen Actions werden ebenfalls automatisch erstellt:

Variable	Zweck
GITHUB_OUTPUT	Actions schreiben ihre Outputs hierhin
GITHUB_ENV	Actions setzen Umgebungsvariablen hierhin
GITHUB_PATH	Actions fuegen PATH-Eintraege hierhin hinzu
GITHUB_STATE	Actions speichern ihren State hierhin
GITHUB_STEP_SUMMARY	Actions schreiben ihre Zusammenfassungen hierhin

---

Arbeitsverzeichnis

Standardmaessig setzt actrun das Arbeitsverzeichnis auf GITHUB_WORKSPACE fuer GitHub Actions Workflow-Graphs. Du kannst dies mit der Umgebungsvariable ACT_CWD ueberschreiben:

macOS / Linux

export ACT_CWD="/path/to/custom/workdir"

Windows

PowerShell

$env:ACT_CWD = "C:\path\to\custom\workdir"

Command Prompt

set ACT_CWD=C:\path\to\custom\workdir

ACT_CWD hat Vorrang vor GITHUB_WORKSPACE, wenn beide gesetzt sind.

---

Optionale Variablen

Falls eine Action zusaetzliche Variablen benoetigt, fuege sie deiner Umgebung hinzu:

# Workflow-Metadaten
export GITHUB_WORKFLOW="My Workflow"
export GITHUB_JOB="build"
export GITHUB_RUN_ID="1"
export GITHUB_RUN_NUMBER="1"

# GitHub URLs
export GITHUB_SERVER_URL="https://github.com"
export GITHUB_API_URL="https://api.github.com"
export GITHUB_GRAPHQL_URL="https://api.github.com/graphql"

# Benutzerinfos (durch deine Daten ersetzen)
export GITHUB_REPOSITORY_OWNER="your-username"
export GITHUB_ACTOR="your-username"

---

Fehlerbehebung

Action schlaegt fehl mit ‘GITHUB_WORKSPACE environment variable is required’

Stelle sicher, dass GITHUB_WORKSPACE mit dem Pfad zu deinem Git-Repository gesetzt ist, bevor du actrun ausfuehrst.

Action schlaegt fehl mit ‘GITHUB_EVENT_NAME environment variable is required’

Setze GITHUB_EVENT_NAME auf den Event-Typ (z.B. push, pull_request, workflow_dispatch).

Action findet Tools oder Cache nicht

Stelle sicher, dass RUNNER_TOOL_CACHE auf ein beschreibbares Verzeichnis zeigt:

mkdir -p ~/.actrun/tool-cache

Action verhaelt sich anders als auf GitHub

Einige Actions pruefen bestimmte Umgebungswerte. Versuche Folgendes hinzuzufuegen:

export RUNNER_ENVIRONMENT="github-hosted"
export ImageOS="ubuntu24"  # oder macos15, win25