Configuration du runner GitHub Actions

Actionforge vous permet de debugger des graphs de workflow GitHub Actions sur votre machine, éliminant les bugs de workflow et réduisant les coûts des runners GitHub. Quand actrun détecte un graph de workflow GitHub Actions (c’est-à-dire un graph créé à partir du template GitHub Actions workflow), il configure automatiquement un environnement GitHub Actions simulé pour que vous puissiez tester vos workflows localement avant de push sur GitHub.

Configuration de la session de debug

Quand vous démarrez une session de debug pour un graph de workflow GitHub Actions, 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é. Il sera utilisé comme GITHUB_WORKSPACE.
3. Définir le GitHub Token — 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 avec les 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 GitHub Access Token

Beaucoup de 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 nécessaires à vos actions. 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é

N’incluez jamais votre token dans le contrôle de version. Pensez à 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 jusqu’à 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

Quand actrun détecte un graph de workflow GitHub Actions exécuté en dehors de GitHub Actions, il configure automatiquement les variables d’environnement suivantes à partir de 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	Emplacement du cache d’outils des actions

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

Variable	Purpose
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 état ici
GITHUB_STEP_SUMMARY	Les actions écrivent leurs résumés ici

---

Répertoire de travail

Par défaut, actrun définit le répertoire de travail à GITHUB_WORKSPACE pour les graphs de workflow GitHub Actions. Vous pouvez le remplacer 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 quand les deux sont définis.

---

Variables optionnelles

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

# Métadonnées 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 informations)
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