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 : figez la version, 0.2.89 minimum, les précédentes portent deux CVE
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

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

act lit vos fichiers YAML dans .github/workflows/, crée des conteneurs Docker qui imitent les runners GitHub, puis exécute les jobs dans cet environnement. Les journaux, les artefacts et le statut final s'affichent dans votre terminal, sans qu'aucune minute Actions ne soit consommée.

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

act est un binaire Go statique sans dépendance système : l'installation se résume à récupérer un exécutable et à le placer dans le PATH. Les gestionnaires de paquets ci-dessous font ce travail pour vous et gèrent la mise à jour ; la méthode manuelle vaut surtout quand vous devez figer une version précise, par exemple pour qu'une équipe entière teste avec le même comportement.

N'installez pas une version antérieure à 0.2.86

Ce guide utilise la version v0.2.89, publiée le 1er juin 2026. Toute version antérieure à 0.2.86 est vulnérable à deux failles de gravité haute, corrigées le 25 mars 2026 : CVE-2026-34041 permet une injection d'environnement par les commandes set-env et add-path laissées sans restriction, et CVE-2026-34042 une injection dans le serveur de cache qu'act embarque. Les versions concernées le disent elles-mêmes au lancement, par un avertissement qui nomme les deux identifiants.

C'est une raison de plus de figer la version plutôt que de laisser un gestionnaire de paquets décider pour vous : sur un poste mis à jour il y a six mois, brew install act peut très bien servir une version d'avant le correctif. La méthode manuelle ci-dessous, avec son numéro écrit en toutes lettres, est la seule qui vous dise ce que vous installez.

macOS

Avec Homebrew :

brew install act

Linux

Avec Homebrew :

brew install act

Avec asdf-vm :

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

Depuis les releases GitHub, avec vérification de l'empreinte publiée par le projet :

VERSION=0.2.89
curl -sSL -O "https://github.com/nektos/act/releases/download/v${VERSION}/act_Linux_x86_64.tar.gz"
curl -sSL -O "https://github.com/nektos/act/releases/download/v${VERSION}/checksums.txt"

# Doit afficher "act_Linux_x86_64.tar.gz: OK" avant toute extraction
sha256sum --check --ignore-missing checksums.txt

tar -xzf act_Linux_x86_64.tar.gz act
sudo install -m 0755 act /usr/local/bin/act

Le fichier checksums.txt est publié par le pipeline de release d'act à côté des archives, et c'est lui qui rend la vérification possible. Si sha256sum --check ne répond pas OK, arrêtez-vous là : l'archive a été altérée ou le téléchargement est incomplet.

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.89

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

L'option -W attend un chemin, pas le name: déclaré dans le fichier, et c'est une confusion fréquente. Pointez-la sur un fichier précis pour n'exécuter que celui-là, ou sur un répertoire pour restreindre la recherche. Sans -W, act balaie tout .github/workflows/, ce qui devient vite pénible sur un dépôt qui en compte une dizaine.

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

# Par répertoire : tous les workflows d'un dossier
act -W .github/workflows/

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-24.04@sha256:c58e2b36…
[CI/test]   🐳  docker pull image=catthehacker/ubuntu:act-24.04@sha256:c58e2b36…
[CI/test]   🐳  docker create image=catthehacker/ubuntu:act-24.04@sha256:c58e2b36…
[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

Avant de lancer quoi que ce soit, act -l donne l'inventaire de ce qu'act a réellement compris de vos fichiers. C'est le premier réflexe de diagnostic : un job absent de cette liste ne s'exécutera jamais, en général parce que son événement déclencheur ne correspond pas à celui simulé, ou parce que le fichier YAML est mal placé.

# 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

Cette forme convient à un test ponctuel, pas à un usage régulier : la valeur passe dans l'historique du shell et reste visible dans ps pendant l'exécution. Si vous omettez la valeur (-s GITHUB_TOKEN), act reprend la variable d'environnement du même nom, et à défaut vous la demande de façon interactive, sans jamais l'écrire en clair sur la ligne de commande.

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.recette.interne.lan

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-24.04@sha256:c58e2b364da03b0c804c7d660f2ecbedf2f221a382b9baa0b344b0144780ff43
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04@sha256:3488f78aa97770c8d5d835f2913c1a782d3121ad3f2aafb17054fb1d554ea4e1
--container-architecture linux/amd64

Chaque ligne correspond à une option de la commande act.

L'image du runner s'épingle comme une action. Le tag act-latest, que la plupart des tutoriels recommandent, est mobile : l'image qu'il désigne change sans prévenir, et votre exécution locale cesse alors de reproduire celle de vos collègues. Le tag act-24.04 correspond au label ubuntu-24.04 que vos workflows demandent, et le digest qui le suit fige l'image exactement. C'est la règle que cette formation applique aux actions ; elle vaut tout autant pour le conteneur qui les exécute.

Images Docker personnalisées

act utilise des images Docker qui imitent les runners GitHub, sans les reproduire : les images par défaut sont plus légères et embarquent donc moins d'outils. Un workflow qui échoue sur un command not found alors qu'il passe sur GitHub désigne presque toujours cette différence d'image :

# Image officielle du projet, épinglée par digest
act -P ubuntu-24.04=catthehacker/ubuntu:act-24.04@sha256:c58e2b364da03b0c804c7d660f2ecbedf2f221a382b9baa0b344b0144780ff43

# Ou votre propre image, figée par sa version
act -P ubuntu-24.04=mon-registry/mon-image:2.4.0

Mode verbeux pour le debug

--verbose est un interrupteur booléen, pas un niveau : act n'a qu'un seul palier de verbosité, et répéter le drapeau ne change rien à la sortie. Ce mode sert surtout à comprendre ce qu'act a chargé et quel contexte Git il a déduit du dépôt local, deux causes fréquentes de divergence entre une exécution locale et le vrai runner.

# 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 le contexte Git qu'act a déduit du dépôt local. Deux options le complètent, et elles ne servent pas la même chose :

# Logs structurés, exploitables par un outil d'analyse
act --json

# Activer les logs de debug côté GitHub Actions (::debug::)
act -s ACTIONS_STEP_DEBUG=true -s ACTIONS_RUNNER_DEBUG=true

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-24.04@sha256:c58e2b36…
*DRYRUN* [CI/test]   🐳  docker pull image=catthehacker/ubuntu:act-24.04@sha256:c58e2b36…
*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
Aucun ordonnanceur	act schedule joue un workflow on: schedule, mais rien ne le déclenche à l'heure dite : le cron: n'est jamais évalué
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	--cache-server-path rend un vrai cache-hit au second passage, mais le cache reste local à votre poste
Artefacts	Le serveur intégré (--artifact-server-path) implémente l'API, mais refuse upload-artifact v7 et download-artifact v8 : restez en v5 ou v6 en local
Marketplace	Certaines actions tierces ont des incompatibilités
Filtres de déclencheur ignorés	branches:, tags: et paths: ne sont pas évalués : le job tourne quelle que soit la branche locale ou le fichier modifié

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

Le drapeau --reuse (-r) empêche act de supprimer le conteneur à la fin d'un workflow réussi, ce qui permet de garder l'état entre deux exécutions et d'entrer dans le conteneur avec docker exec pour inspecter le système de fichiers. Attention à la contrepartie : le conteneur conservé garde les fichiers de l'exécution précédente, donc un build qui ne passe que grâce à un artefact résiduel vous donnera une fausse confiance. Nettoyez-le avant la validation finale.

# Exécuter un job précis avec logs détaillés
act -j build -v

# Conserver le conteneur d'un run réussi pour l'inspecter
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-24.04
    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-24.04@sha256:c58e2b36…
[Matrix Build/build-2] 🚀  Start image=catthehacker/ubuntu:act-24.04@sha256:c58e2b36…
[Matrix Build/build-3] 🚀  Start image=catthehacker/ubuntu:act-24.04@sha256:c58e2b36…
[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-24.04
    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

Le workflow ci-dessous enchaîne trois jobs liés par needs: et applique les règles de durcissement de la formation : actions épinglées par SHA avec le tag en commentaire, permissions: {} au niveau du workflow puis le strict minimum par job, persist-credentials: false sur le checkout et une version de runner figée. C'est cette combinaison qu'act vous permet de vérifier localement, avant le premier push.

.github/workflows/ci.yml

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

# Aucun droit par défaut : chaque job demande le minimum
permissions: {}

jobs:
  lint:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Lint
        run: echo "Linting..."

  test:
    runs-on: ubuntu-24.04
    needs: lint
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Run tests
        run: echo "Tests passed!"

  build:
    runs-on: ubuntu-24.04
    needs: test
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - 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

Presque tous les échecs d'act se rangent en deux catégories. Soit Docker ne répond pas comme attendu (démon arrêté, permissions du socket, architecture du processeur), soit l'image du runner ne contient pas l'outil que le workflow appelle. Le message d'erreur pointe rarement vers la vraie cause : commencez par docker info, puis par l'image effectivement utilisée, qu'act affiche en tête de chaque job.

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, épinglée : -P ubuntu-24.04=catthehacker/ubuntu:act-24.04@sha256:c58e2b36…
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
Le job tourne alors que le filtre devrait l'exclure	branches: et paths: ne sont pas évalués	Comportement normal de act : la vérification du filtre se fait sur GitHub, avec gh run list
Cache actions/cache partiel	Stockage local uniquement	Normal, le cache fonctionne mais n'est pas partagé entre runs

Glissez pour voir

Debug avancé

# Logs détaillés
act -v

# 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)

Les quatre premières lignes couvrent l'essentiel d'un usage quotidien ; les suivantes servent quand quelque chose résiste ou que vous testez un cas particulier. Retenez surtout leur enchaînement : act -l pour vérifier ce qui est détecté, act -n pour valider la structure sans créer de conteneur, puis act -j pour n'exécuter que le job qui vous intéresse.

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	Mode verbeux (drapeau booléen, -vv n'ajoute rien)
act --secret-file .secrets	Charger les secrets
act --matrix node:20	Filtrer une combinaison de matrice
act -P ubuntu-24.04=catthehacker/ubuntu:act-24.04@sha256:…	Définir l'image, épinglée par digest
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 : mode verbeux (-v, un seul palier) 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

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

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 ?

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

Comment installer act sur Linux, macOS et Windows ?

Comment gérer les secrets avec act ?

Comment choisir et configurer les images Docker pour act ?

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

Comment débugger un workflow avec act ?

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

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

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

×

📖 Voir la documentation →