act : exécuter les workflows GitHub Actions en local

Vous venez de modifier votre workflow GitHub Actions. Pour savoir s’il fonctionne, vous devez pousser le code, attendre que le runner démarre, puis découvrir — souvent — qu’une erreur de syntaxe ou un chemin incorrect fait tout échouer. Retour au code, nouveau push, nouvelle attente…

act résout ce problème en exécutant vos workflows localement, sur votre machine. Vous pouvez itérer en quelques secondes au lieu de plusieurs minutes, sans consommer vos minutes GitHub Actions.

Qu’est-ce que act ?

act est un outil en ligne de commande qui simule l’environnement GitHub Actions sur votre machine. Il utilise Docker pour créer des conteneurs qui imitent les runners GitHub, puis exécute vos workflows comme s’ils tournaient sur GitHub.

Concrètement, act vous permet de :

Tester vos workflows avant de les pousser
Débugger les erreurs sans attendre le runner distant
Développer des workflows complexes de manière itérative
Exécuter des workflows manuellement (workflow_dispatch)

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

Avec Homebrew :

brew install act

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

Avec Chocolatey :

choco install act-cli

Avec Scoop :

scoop install act

Vérification de l’installation :

act --version

La commande doit afficher la version installée (ex: act version 0.2.74).

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

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

# 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

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

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

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 :

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 :

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

# Encore plus détaillé
act -vv

Exécution à sec (dry-run)

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

act -n

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

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 toutes les combinaisons de la matrice
act -W .github/workflows/matrix.yml

# Exécuter une seule combinaison
act -j build -m

Tester un workflow_dispatch avec inputs

Pour un workflow avec des inputs :

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

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

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

Puis :

act workflow_dispatch -e event.json

Intégration dans le flux de développement

Script de validation pré-push

Créez un hook Git pour valider avant chaque 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 :

# 1. Valider la syntaxe avec actionlint
actionlint .github/workflows/*.yml

# 2. Si OK, tester avec act
act -n

Voir le guide actionlint pour la validation statique des workflows.

Dépannage

”Cannot connect to Docker daemon”

Symptôme : act ne peut pas se connecter à Docker.

Solutions :

# Vérifier que Docker tourne
docker info

# Sur Linux, ajouter votre utilisateur au groupe docker
sudo usermod -aG docker $USER
# Puis déconnectez-vous et reconnectez-vous

“Image not found” ou pull très long

Symptôme : act tente de télécharger une image de 18 Go.

Solution : utiliser une image plus légère :

act -P ubuntu-24.04=catthehacker/ubuntu:act-latest

“Action not found” ou incompatibilité

Symptôme : une action du Marketplace ne fonctionne pas.

Solutions :

Vérifier la compatibilité sur le repo act
Utiliser une image plus complète
Accepter que certaines actions nécessitent le vrai GitHub

Architecture ARM (Mac M1/M2)

Sur les Macs Apple Silicon, certaines images ne fonctionnent pas nativement :

# Forcer l'architecture x86_64 via émulation
act --container-architecture linux/amd64

Cela sera plus lent mais plus compatible.

À 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 et possibilité de garder les conteneurs pour investigation.

Limitations connues

act n’est pas un remplacement complet — validez toujours sur GitHub.

Points clés :

act exécute vos workflows GitHub Actions localement via Docker
Utilisez .secrets et .actrc pour configurer votre environnement
Commencez avec l’image Medium, passez à une plus complète si nécessaire
Combinez act avec actionlint pour une validation complète
Toujours faire un test final sur GitHub avant merge

Liens utiles

Repository act sur GitHub — Documentation et issues
Images Docker disponibles — Images compatibles act
Debug des workflows — Techniques de dépannage