Debug Sessions

Debug Sessions verbinden den visuellen Web-Editor mit deiner lokalen Infrastruktur und werden ausschliesslich fuer Entwicklungszwecke genutzt. Indem du einen lokalen Runner mit einer Debug Session verbindest, kannst du Graphs auf deiner eigenen Maschine ausfuehren, waehrend du sie in Echtzeit im Browser entwirfst.

Interface-Steuerung

Die Steuerungsleiste verwaltet den Lebenszyklus deiner Debug Session. Standardmaessig ist deine Debug Session deaktiviert.

Nach der Aktivierung erscheint ein Debug Session einrichten-Dialog. Die Einrichtungsschritte haengen vom Typ des Graphs ab, den du debuggst.

Standalone

Der Einrichtungsdialog fuehrt dich durch drei Schritte:

1. Runner herunterladen — Lade den Actionforge Runner herunter fuer deine Plattform.
2. Arbeitsverzeichnis festlegen (Optional) — Lege ein Arbeitsverzeichnis fuer den Runner fest. Falls nicht gesetzt, wird ein zufaelliger temporaerer Ordner verwendet.
3. Session Token kopieren — Kopiere den Session Token und fuege ihn in deinen lokalen Runner ein, um dich zu verbinden.

Wenn du deinen lokalen Runner startest, musst du diesen Token angeben, um deine Maschine fuer die Debug Session zu autorisieren.

Alternativ kannst du statt der Konfiguration ueber den Browser den Runner die Session einrichten lassen, indem du das Flag --create-debug-session verwendest. Das ueberspringt den Einrichtungsdialog und zeigt einen Link in der Konsole an, wenn du deinen Graph manuell ausfuehrst. Das Oeffnen des Links in deinem Browser verbindet dich sofort mit der bereits laufenden Debug Session.

actrun --create-debug-session ./my_graph.act

GitHub Actions

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, richtet es automatisch eine simulierte GitHub Actions-Umgebung ein, sodass du deine Workflows lokal testen kannst, bevor du auf GitHub pushst.

Der Einrichtungsdialog enthaelt 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. Dieser 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 der Verwendung von 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	Beschreibung
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

GitLab CI (Demnächst verfügbar)

GitLab CI Support kommt bald.

Sobald verbunden, werden die Debug-Steuerungen aktiv.

Runner-Trennung

Falls der Runner sich zu irgendeinem Zeitpunkt trennt, erscheint ein modaler Dialog, der dir die Wiederverbindung ermoeglicht. Der Dialog zeigt erneut den Session Token an und wartet darauf, dass der Runner sich wieder verbindet.

Verschluesselung

Jegliche Kommunikation zwischen deinem Browser und deinem actrun-Programm ist Ende-zu-Ende-verschluesselt mit AES-256-GCM. Der Actionforge-Server fungiert lediglich als Relay und kann keine der waehrend einer Debug Session ausgetauschten Nachrichten lesen oder entschluesseln. Dies umfasst unter anderem die Graph-Datei, Konfigurationsdaten wie Secrets oder Umgebungsvariablen sowie Logs.

Wenn eine Debug Session erstellt wird, generiert dein Browser einen einzigartigen Verschluesselungsschluessel, der in deinem Session Token eingebettet ist. Dieser Token muss manuell ueber die Zwischenablage von deinem Browser zu deinem actrun-Programm kopiert werden, sodass der Server ihn niemals sieht.

Der Quellcode des Verschluesselungsmechanismus in actrun ist hier verfuegbar.