act : exécuter les workflows GitHub Actions en local

Testez vos workflows GitHub Actions en quelques secondes, sans pousser sur GitHub. act exécute vos workflows localement via Docker, permettant un développement itératif rapide. Vous économisez vos minutes Actions et évitez les allers-retours frustrants push → attente → échec → correction → push.

TL;DR — Les 5 points clés

1. act exécute vos workflows GitHub Actions localement via Docker
2. Installation : brew install act (macOS/Linux) ou choco install act-cli (Windows)
3. Secrets : fichier .secrets (format clé=valeur) + --secret-file .secrets
4. Images : choisissez Medium (~500 Mo) pour la plupart des cas
5. Limitation : act ne remplace pas GitHub — validez toujours sur le vrai runner

Architecture de act

act lit vos fichiers YAML dans .github/workflows/, crée des conteneurs Docker qui imitent les runners GitHub, et exécute les jobs comme s’ils tournaient sur GitHub. Les résultats (logs, artifacts, status) sont affichés localement.

Ce que vous allez apprendre

• Installer act sur Linux, macOS et Windows
• Exécuter des workflows avec différents événements (push, PR, workflow_dispatch)
• Gérer les secrets et variables d’environnement
• Configurer les images Docker optimales
• Débugger efficacement avec les options avancées

Prérequis

Avant d’installer act, vous devez avoir :

• Docker installé et en cours d’exécution (act crée des conteneurs)
• Un terminal (bash, zsh, PowerShell)
• Un projet avec des workflows dans .github/workflows/

Pour vérifier que Docker fonctionne :

docker version

Si Docker n’est pas installé, consultez le guide Docker.

Installation

Version actuelle

Ce guide utilise la verion v0.2.84 (décembre 2025) d’act.

macOS

Avec Homebrew :

brew install act

Linux

Avec Homebrew :

brew install act

Avec asdf-vm :

asdf plugin add act
asdf install act latest
asdf set --home act latest

Depuis les releases GitHub :

# Télécharger la dernière version
curl -sSL https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Windows

Avec Chocolatey :

choco install act-cli

Avec Scoop :

scoop install act

Vérification de l’installation :

act --version

Sortie attendue

act version 0.2.84

Premier lancement

À la première exécution, act vous demande quelle image Docker utiliser pour simuler les runners GitHub. Trois options sont proposées :

Image	Taille	Compatibilité
Micro (~200 Mo)	Très légère	Limitée (manque beaucoup d’outils)
Medium (~500 Mo)	Équilibrée	Bonne pour la plupart des cas
Large (~18 Go)	Complète	Proche de l’environnement GitHub

Glissez pour voir

Pour commencer, choisissez Medium. Vous pourrez changer plus tard.

# Premier lancement - choisissez Medium
act

act sauvegarde votre choix dans ~/.actrc pour les prochaines exécutions.

Utilisation de base

Exécuter le workflow par défaut

La commande act sans argument simule un événement push et exécute les workflows qui répondent à cet événement :

act

Exécuter un workflow spécifique

# Par chemin de fichier
act -W .github/workflows/ci.yml

# Par nom du workflow (défini dans name:)
act -W .github/workflows/build.yml

Exécuter un job spécifique

Si votre workflow contient plusieurs jobs, vous pouvez n’en exécuter qu’un :

# Exécuter uniquement le job "test"
act -j test

Sortie

[CI/test] 🚀  Start image=catthehacker/ubuntu:act-latest
[CI/test]   🐳  docker pull image=catthehacker/ubuntu:act-latest
[CI/test]   🐳  docker create image=catthehacker/ubuntu:act-latest
[CI/test] ⭐ Run Main Checkout
[CI/test]   ✅  Success - Main Checkout
[CI/test] ⭐ Run Main Run tests
| Tests passed!
[CI/test]   ✅  Success - Main Run tests
[CI/test] 🏁  Job succeeded

Les icônes indiquent le statut : ⭐ step en cours, ✅ succès, ❌ échec.

# Exécuter uniquement le job "build" du workflow ci.yml
act -W .github/workflows/ci.yml -j build

Simuler différents événements

GitHub Actions se déclenche sur différents événements. act peut les simuler :

# Simuler un push (par défaut)
act push

# Simuler une pull request
act pull_request

# Simuler un workflow manuel
act workflow_dispatch

# Simuler un événement de release
act release

Lister les workflows disponibles

# Voir tous les workflows et leurs jobs
act -l

Sortie

Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      test    test      CI             ci.yml         push,pull_request
1      build   build     CI             ci.yml         push,pull_request

Chaque ligne indique : le stage (ordre d’exécution), l’ID du job, son nom, le workflow parent et les événements déclencheurs.

# Voir les jobs pour un événement spécifique
act -l push
act -l pull_request

Visualiser le graphe des dépendances

Pour voir graphiquement l’ordre d’exécution des jobs :

act -g

Sortie

 ╭──────╮
 │ test │
 ╰──────╯
    ⬇
 ╭───────╮
 │ build │
 ╰───────╯

Utile pour comprendre les dépendances needs: entre jobs.

Gestion des secrets

Les workflows utilisent souvent des secrets (${{ secrets.TOKEN }}). act propose plusieurs méthodes pour les fournir.

Fichier .secrets

Créez un fichier .secrets à la racine du projet :

# .secrets (format clé=valeur)
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
NPM_TOKEN=npm_xxxxxxxxxx
AWS_ACCESS_KEY_ID=AKIAXXXXXXXX
AWS_SECRET_ACCESS_KEY=xxxxxxxxxx

Ensuite, utilisez :

act --secret-file .secrets

Sécurité

Ajoutez .secrets à votre .gitignore pour ne jamais le commiter :

echo ".secrets" >> .gitignore

Secrets en ligne de commande

Pour des tests rapides ou en CI :

act -s GITHUB_TOKEN=ghp_xxxx -s MY_SECRET=valeur

Variables d’environnement

Pour les variables ${{ vars.X }} (non sensibles), utilisez un fichier .vars :

.vars

ENVIRONMENT=development
API_URL=https://api-dev.example.com

act --var-file .vars

Configuration avancée

Fichier .actrc

Créez un fichier .actrc à la racine du projet pour sauvegarder vos options :

.actrc

--secret-file .secrets
--var-file .vars
-P ubuntu-24.04=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
--container-architecture linux/amd64

Chaque ligne correspond à une option de la commande act.

Images Docker personnalisées

act utilise des images Docker qui imitent les runners GitHub. Par défaut, ces images sont plus légères mais moins complètes. Pour plus de compatibilité :

# Utiliser une image plus complète
act -P ubuntu-24.04=catthehacker/ubuntu:act-latest

# Ou votre propre image
act -P ubuntu-24.04=mon-registry/mon-image:tag

Mode verbeux pour le debug

# Logs détaillés
act -v

Extrait sortie verbose

level=debug msg="Loading workflows from '.github/workflows'"
level=debug msg="Found workflow 'ci.yml'"
level=debug msg="Planning job: test"
level=debug msg="Job.Steps: Checkout"
level=debug msg="Job.Steps: Run tests"
level=debug msg="using github ref: refs/heads/main"
level=debug msg="Detected CPUs: 16"

Le mode -v révèle le chargement des workflows, la planification des jobs et les variables d’environnement Git détectées.

# Encore plus détaillé (inclut les appels Docker)
act -vv

Exécution à sec (dry-run)

Pour voir ce qui serait exécuté sans vraiment l’exécuter :

act -n

Sortie dry-run

*DRYRUN* [CI/test] ⭐ Run Set up job
*DRYRUN* [CI/test] 🚀  Start image=catthehacker/ubuntu:act-latest
*DRYRUN* [CI/test]   🐳  docker pull image=catthehacker/ubuntu:act-latest
*DRYRUN* [CI/test]   ✅  Success - Set up job
*DRYRUN* [CI/test] ⭐ Run Main Checkout
*DRYRUN* [CI/test]   ✅  Success - Main Checkout
*DRYRUN* [CI/test] 🏁  Job succeeded

Le préfixe *DRYRUN* indique qu’aucun conteneur n’est créé. Utile pour valider la syntaxe et la structure avant une vraie exécution.

Limitations de act

act ne peut pas reproduire 100% de l’environnement GitHub Actions. Voici les principales limitations à connaître :

Limitation	Explication
Événements limités	schedule, deployment, page_build ne sont pas supportés
API GitHub limitée	Pas d’accès à l’API GitHub comme en production
Services Docker	Les containers de service peuvent se comporter différemment
Cache	actions/cache fonctionne partiellement (stockage local)
Artifacts	actions/upload-artifact crée des fichiers locaux, pas d’API
Marketplace	Certaines actions tierces ont des incompatibilités

Glissez pour voir

Quand utiliser act :

• Tests de syntaxe et structure
• Développement itératif de workflows
• Validation des commandes et scripts
• Debug de problèmes de logique

Quand NE PAS compter sur act :

• Validation finale (toujours tester sur GitHub)
• Tests d’intégration avec l’API GitHub
• Workflows avec services complexes

Cas d’usage courants

Debug interactif

# Exécuter avec logs détaillés
act -j build -v

# Garder le conteneur après l'exécution pour investiguer
act --reuse

Workflow avec matrice

act exécute automatiquement toutes les combinaisons de la matrice en parallèle :

.github/workflows/matrix.yml

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [18, 20, 22]
    steps:
      - run: echo "Testing Node.js ${{ matrix.node }}"

act -W .github/workflows/matrix.yml

Sortie (3 jobs parallèles)

[Matrix Build/build-1] 🚀  Start image=catthehacker/ubuntu:act-latest
[Matrix Build/build-2] 🚀  Start image=catthehacker/ubuntu:act-latest
[Matrix Build/build-3] 🚀  Start image=catthehacker/ubuntu:act-latest
[Matrix Build/build-1] ⭐ Run Main
| Testing Node.js 18
[Matrix Build/build-2] ⭐ Run Main
| Testing Node.js 20
[Matrix Build/build-3] ⭐ Run Main
| Testing Node.js 22

Pour n’exécuter qu’une seule combinaison de la matrice :

# Filtrer par valeur de matrice
act --matrix node:20

Tester un workflow_dispatch avec inputs

Pour un workflow avec des inputs :

.github/workflows/deploy.yml

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy'
        required: true
        type: choice
        options: [dev, staging, prod]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to ${{ github.event.inputs.environment }}"

Créez un fichier d’événement JSON :

event.json

{
  "inputs": {
    "environment": "staging"
  }
}

Puis exécutez :

act workflow_dispatch -e event.json

Sortie

[Deploy/deploy] ⭐ Run Main
| Deploying to staging
[Deploy/deploy]   ✅  Success - Main
[Deploy/deploy] 🏁  Job succeeded

Intégration dans le flux de développement

Script de validation pré-push

Créez un hook Git pour valider avant chaque push :

.git/hooks/pre-push

#!/bin/bash
echo "🔍 Validation du workflow CI..."
act -n -W .github/workflows/ci.yml

if [ $? -ne 0 ]; then
    echo "❌ Le workflow a des erreurs. Push annulé."
    exit 1
fi

echo "✅ Workflow valide"

N’oubliez pas de rendre le script exécutable :

chmod +x .git/hooks/pre-push

Combinaison avec actionlint

Pour une validation complète, combinez la validation statique et l’exécution :

# 1. Valider la syntaxe avec actionlint (rapide, sans Docker)
actionlint .github/workflows/*.yml

# 2. Si OK, valider la structure avec act en dry-run
act -n

# 3. Si tout passe, exécuter réellement
act

Voir le guide actionlint pour la validation statique des workflows.

Exemple complet

Voici un workflow typique et son exécution avec act :

.github/workflows/ci.yml

name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint
        run: echo "Linting..."

  test:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: echo "Tests passed!"

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: echo "Building..."

# Visualiser la structure
act -g

Graphe des dépendances

 ╭──────╮
 │ lint │
 ╰──────╯
    ⬇
 ╭──────╮
 │ test │
 ╰──────╯
    ⬇
 ╭───────╮
 │ build │
 ╰───────╯

# Exécuter uniquement les tests (avec ses dépendances)
act -j test

Dépannage

Problème	Cause	Solution
Cannot connect to Docker daemon	Docker non démarré ou permissions	docker info pour vérifier. Sur Linux : sudo usermod -aG docker $USER puis logout/login
Image not found / pull 18 Go	Image Large sélectionnée par défaut	Utiliser Medium : -P ubuntu-24.04=catthehacker/ubuntu:act-latest
Action not found	Action Marketplace incompatible	Vérifier compatibilité sur repo act, utiliser image Full
exec format error (Mac M1/M2)	Image x86 sur ARM	Ajouter --container-architecture linux/amd64
Secret non trouvé	Fichier .secrets absent ou mal formaté	Vérifier format CLE=valeur (pas d’espaces) et --secret-file .secrets
Événement non supporté	schedule, deployment non implémentés	Tester sur GitHub, act ne supporte pas tous les événements
Cache actions/cache partiel	Stockage local uniquement	Normal, le cache fonctionne mais n’est pas partagé entre runs

Glissez pour voir

Debug avancé

# Logs très détaillés
act -vv

# Garder le conteneur pour investigation
act --reuse

# Activer les logs de debug GitHub
act -s ACTIONS_STEP_DEBUG=true -s ACTIONS_RUNNER_DEBUG=true

Aide-mémoire (cheatsheet)

Commande	Description
act	Exécuter tous les workflows (événement push)
act -l	Lister tous les jobs
act -g	Afficher le graphe des dépendances
act -n	Dry-run (validation sans exécution)
act -j <job>	Exécuter un job spécifique
act pull_request	Simuler une pull request
act workflow_dispatch -e event.json	Déclencher avec inputs
act -v / act -vv	Mode verbeux / très verbeux
act --secret-file .secrets	Charger les secrets
act --matrix node:20	Filtrer une combinaison de matrice
act -P ubuntu-24.04=catthehacker/ubuntu:act-latest	Définir l’image
act --container-architecture linux/amd64	Forcer l’architecture (Mac M1/M2)

Glissez pour voir

À retenir

• Itération rapide : testez vos workflows en secondes sans pousser sur GitHub
• Économie de ressources : pas de consommation de minutes Actions pendant le développement
• Debug efficace : logs verbeux (-v, -vv) et possibilité de garder les conteneurs (--reuse)
• Configuration : utilisez .secrets et .actrc pour centraliser vos options
• Images : commencez avec Medium (~500 Mo), passez à Large si nécessaire
• Validation complète : combinez act avec actionlint pour détecter toutes les erreurs
• Sécurité : maintenez act à jour (correctifs réguliers sur x/crypto, SELinux)
• Limitation : act n’est pas un remplacement complet — validez toujours sur GitHub avant merge

Prochaines étapes

actionlint : validation statique Détectez les erreurs de syntaxe avant même d'exécuter vos workflows

GitHub Actions : guide complet Maîtrisez les workflows, jobs, steps et expressions GitHub Actions

Optimiser les performances Cache, matrices, concurrency pour des pipelines rapides

Ressources

• Site officiel : github.com/nektos/act
• Images Docker : catthehacker/docker_images
• Changelog : Releases

Questions fréquentes

Qu'est-ce que act et à quoi sert-il ?

act est un outil CLI qui exécute vos workflows GitHub Actions localement sur votre machine via Docker. Il parse les fichiers YAML dans .github/workflows/, crée des conteneurs Docker imitant les runners GitHub, et exécute les jobs. Cela permet de tester et débugger les workflows sans pousser le code sur GitHub.

Quelle est la différence entre act et les runners GitHub Actions ?

act utilise Docker pour simuler les runners GitHub localement. Les images sont plus légères (~500 Mo vs ~18 Go) mais moins complètes. Certaines fonctionnalités ne sont pas supportées : événements schedule/deployment, API GitHub complète, actions/cache partiel. act est idéal pour le développement itératif, mais la validation finale doit toujours se faire sur GitHub.

Comment installer act sur Linux, macOS et Windows ?

Sur macOS/Linux : brew install act. Sur Linux également : curl -sSL https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash ou via asdf (asdf plugin add act && asdf install act latest). Sur Windows : choco install act-cli ou scoop install act. Prérequis : Docker doit être installé et en cours d'exécution.

Comment gérer les secrets avec act ?

Trois méthodes : 1) Fichier .secrets (format clé=valeur) avec act --secret-file .secrets. 2) Ligne de commande : act -s TOKEN=valeur. 3) Variables d'environnement du shell. Pour les variables non sensibles (vars), utiliser .vars avec --var-file .vars. Important : ajouter .secrets au .gitignore.

Comment choisir et configurer les images Docker pour act ?

act propose 3 tailles d'images : Micro (~200 Mo, limitée), Medium (~500 Mo, équilibrée), Large (~18 Go, complète). Configurer dans .actrc : -P ubuntu-24.04=catthehacker/ubuntu:act-latest. Pour Mac M1/M2, ajouter --container-architecture linux/amd64 pour forcer l'émulation x86.

Comment simuler différents événements GitHub avec act ?

act simule push par défaut. Autres événements : act pull_request, act workflow_dispatch, act release. Pour workflow_dispatch avec inputs, créer un fichier event.json avec les inputs et utiliser act workflow_dispatch -e event.json. Lister les workflows : act -l.

Comment débugger un workflow avec act ?

Options de debug : act -v (logs détaillés), act -vv (très détaillé), act -n (dry-run sans exécution). Pour garder le conteneur après exécution : act --reuse. Pour exécuter un job spécifique : act -j nom_job. Combiner avec actionlint pour validation syntaxique avant exécution.

Comment résoudre l'erreur 'Cannot connect to Docker daemon' ?

Cette erreur signifie que Docker n'est pas en cours d'exécution ou que l'utilisateur n'a pas les permissions. Solutions : 1) Vérifier que Docker tourne (docker info). 2) Sur Linux, ajouter l'utilisateur au groupe docker (sudo usermod -aG docker $USER) puis se déconnecter/reconnecter. 3) Vérifier que le socket Docker est accessible.

Comment utiliser act avec des workflows utilisant une matrice de build ?

act exécute automatiquement toutes les combinaisons de la matrice. Pour n'exécuter qu'une seule combinaison : act -j job_name -m. Pour voir les combinaisons avant exécution : act -l. Les matrices avec include/exclude sont supportées. Attention : les matrices volumineuses peuvent être longues à exécuter localement.

Comment combiner act avec actionlint pour une validation complète ?

Workflow recommandé : 1) actionlint valide la syntaxe YAML et détecte les erreurs statiques. 2) act teste l'exécution réelle. Commandes : actionlint .github/workflows/*.yml puis act -n (dry-run) puis act -v (exécution). Créer un hook pre-push pour automatiser la validation avant chaque push.

×

📖 Voir la documentation →