Sessions de debug

Les Sessions de debug font le lien entre l’éditeur visuel web et votre infrastructure locale, et sont utilisées uniquement à des fins de développement. En connectant un runner local à une Session de debug, vous pouvez exécuter des graphs sur votre propre machine tout en les concevant en temps réel dans le navigateur.

Contrôles de l’interface

La barre de contrôle gère le cycle de vie de votre Session de debug. Par défaut, votre session de debug est désactivée.

Une fois activée, une boîte de dialogue Configuration de Session de debug apparaît. Les étapes de configuration dépendent du type de graph que vous déboguez.

Standalone

La boîte de dialogue de configuration vous guide à travers trois étapes :

1. Télécharger le runner — Téléchargez le runner Actionforge pour votre plateforme.
2. Définir le répertoire de travail (Optionnel) — Définissez un répertoire de travail pour le runner. Si non défini, un nouveau dossier temporaire aléatoire est utilisé.
3. Copier le session token — Copiez le session token et collez-le dans votre runner local pour vous connecter.

Lorsque vous démarrez votre runner local, vous devrez fournir ce token pour autoriser votre machine à rejoindre la Session de debug.

Alternativement, au lieu de configurer la session depuis votre navigateur, vous pouvez laisser le runner la configurer en utilisant le flag --create-debug-session. Cela saute la boîte de dialogue de configuration et affiche un lien dans la console lorsque vous exécutez votre graph manuellement. Ouvrir le lien dans votre navigateur vous connecte immédiatement à la session de debug déjà en cours.

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

GitHub Actions

Actionforge vous permet de déboguer les graphs de workflow GitHub Actions sur votre machine, éliminant les bugs de workflow et réduisant les coûts de runner GitHub. Lorsque actrun détecte un graph de workflow GitHub Actions, il configure automatiquement un environnement GitHub Actions simulé pour que vous puissiez tester vos workflows localement avant de les pusher sur GitHub.

La boîte de dialogue de configuration inclut des champs supplémentaires spécifiques à GitHub Actions :

1. Télécharger le runner — Téléchargez le runner Actionforge pour votre plateforme.
2. Définir le chemin du repository local — Entrez le chemin local vers votre repository GitHub cloné. Cela sera utilisé comme GITHUB_WORKSPACE.
3. Définir le token GitHub — Créez un fine-grained personal access token avec des permissions minimales. Le token est chiffré de bout en bout et ne peut être déchiffré que par votre runner local.
4. Copier le session token — Copiez le session token et collez-le dans votre runner local pour vous connecter.

La boîte de dialogue configure l’environnement pour vous — aucune configuration manuelle de variables d’environnement n’est nécessaire lors de l’utilisation des Sessions de debug.

---

Configuration CLI (sans Session de debug)

Si vous préférez exécuter votre graph de workflow GitHub Actions directement depuis la ligne de commande, suivez ces étapes :

1. Télécharger et installer actrun

Téléchargez et installez le runner CLI actrun pour votre plateforme.

Télécharger actrun

Pour des instructions d’installation détaillées, consultez le guide d’installation.

2. Créer un token d’accès GitHub

De nombreuses GitHub Actions nécessitent un GITHUB_TOKEN pour s’authentifier auprès de l’API GitHub. Pour exécuter ces actions localement, créez un fine-grained personal access token :

1. Cliquez sur Generate new token
2. Donnez-lui un nom descriptif (par ex., “actrun local development”)
3. Définissez une date d’expiration
4. Sélectionnez les repositories auxquels vous souhaitez accéder
5. Sous Repository permissions, accordez les permissions dont vos actions ont besoin. Sauf si vous avez besoin de fonctionnalités spécifiques de l’API GitHub, laissez les permissions par défaut qui donnent un accès read aux ressources publiques.
6. Cliquez sur Generate token et copiez le token

Définissez le token comme variable d’environnement avant d’exécuter actrun :

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

Gardez votre token en sécurité

Ne committez jamais votre token dans le contrôle de version. Envisagez d’utiliser un fichier .actconfig (ajouté au .gitignore) ou le flag --env-file avec un fichier .env.

3. Définir les variables d’environnement requises

Naviguez vers la racine de votre repository et définissez les variables d’environnement suivantes :

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	Description
GITHUB_WORKSPACE	Chemin vers la racine de votre repository git. actrun l’utilise pour détecter le nom du repository, la branche et le commit.
GITHUB_EVENT_NAME	L’événement qui a déclenché le workflow (par ex., push, pull_request, workflow_dispatch).

4. Exécuter actrun

actrun my_workflow.act

---

Configuration automatique de l’environnement

Lorsque actrun détecte un graph de workflow GitHub Actions s’exécutant en dehors de GitHub Actions, il configure automatiquement les variables d’environnement suivantes en se basant sur votre repository git :

Variable	Valeur	Description
CI	true	Indique un environnement CI
GITHUB_ACTIONS	true	Indique un environnement GitHub Actions
GITHUB_REPOSITORY	owner/repo	Dérivé du remote git origin
GITHUB_REF	refs/heads/branch	Référence de la branche git actuelle
GITHUB_REF_NAME	branch	Nom de la branche actuelle
GITHUB_SHA	Commit hash	Commit HEAD actuel
RUNNER_OS	macOS / Linux / Windows	Système d’exploitation détecté
RUNNER_ARCH	X64 / ARM64	Architecture CPU détectée
RUNNER_TEMP	Temp directory	Espace temporaire pour les actions
RUNNER_TOOL_CACHE	~/.actrun/tool-cache	Où les actions mettent en cache les outils

Les fichiers suivants pour la communication entre actions sont également créés automatiquement :

Variable	Description
GITHUB_OUTPUT	Les actions écrivent leurs outputs ici
GITHUB_ENV	Les actions définissent les variables d’environnement ici
GITHUB_PATH	Les actions ajoutent des entrées PATH ici
GITHUB_STATE	Les actions sauvegardent leur state ici
GITHUB_STEP_SUMMARY	Les actions écrivent leurs résumés ici

---

Répertoire de travail

Par défaut, actrun définit le working directory à GITHUB_WORKSPACE pour les graphs de workflow GitHub Actions. Vous pouvez le surcharger avec la variable d’environnement ACT_CWD :

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 a la priorité sur GITHUB_WORKSPACE lorsque les deux sont définis.

---

Variables optionnelles

Si une action nécessite des variables supplémentaires, ajoutez-les à votre environnement :

# Metadata du workflow
export GITHUB_WORKFLOW="My Workflow"
export GITHUB_JOB="build"
export GITHUB_RUN_ID="1"
export GITHUB_RUN_NUMBER="1"

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

# Infos utilisateur (remplacez par vos détails)
export GITHUB_REPOSITORY_OWNER="your-username"
export GITHUB_ACTOR="your-username"

---

Dépannage

L’action échoue avec ‘GITHUB_WORKSPACE environment variable is required’

Assurez-vous que GITHUB_WORKSPACE est défini avec le chemin de votre repository git avant d’exécuter actrun.

L’action échoue avec ‘GITHUB_EVENT_NAME environment variable is required’

Définissez GITHUB_EVENT_NAME avec le type d’événement (par ex., push, pull_request, workflow_dispatch).

L’action ne trouve pas les outils ou le cache

Assurez-vous que RUNNER_TOOL_CACHE pointe vers un répertoire accessible en écriture :

mkdir -p ~/.actrun/tool-cache

L’action se comporte différemment que sur GitHub

Certaines actions vérifient des valeurs d’environnement spécifiques. Essayez d’ajouter :

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

GitLab CI (Bientôt disponible)

Le support de GitLab CI arrive bientôt.

Une fois connecté, vous verrez les contrôles de debug devenir actifs.

Déconnexion du runner

Si le runner se déconnecte à tout moment, une boîte de dialogue modale apparaîtra vous permettant de vous reconnecter. La boîte de dialogue affiche à nouveau le session token et attend que le runner se reconnecte.

Chiffrement

Toutes les communications entre votre navigateur et votre programme actrun sont chiffrées de bout en bout en utilisant AES-256-GCM . Le serveur Actionforge agit uniquement comme relais et ne peut ni lire ni déchiffrer aucun des messages échangés pendant une Session de debug. Cela inclut, sans s’y limiter, le fichier graph, les données de configuration comme les secrets ou les variables d’environnement, et les logs.

Lorsqu’une Session de debug est créée, votre navigateur génère une clé de chiffrement unique qui est intégrée dans votre session token. Ce token doit être manuellement copié-collé via votre presse-papiers depuis votre navigateur vers votre programme actrun, de sorte que le serveur ne le voit jamais.

Le code source du mécanisme de chiffrement dans actrun est disponible ici .