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.

Architecture de act

Architecture act : workflow local → Docker → runner container → résultats

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

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.

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, avec vérification de l'empreinte publiée par le projet :

VERSION=0.2.84
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. 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.

Avec Chocolatey :

choco install act-cli

Avec Scoop :

scoop install act

Vérification de l'installation :

act --version

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

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. Pointez-la sur un fichier précis pour n'exécuter que celui-là, ou sur un répertoire pour restreindre la recherche à un sous-ensemble de workflows. 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

[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

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

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

 ╭──────╮
 │ 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

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. Cette forme évite d'écrire le secret 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 :

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

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

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. Pour aller plus loin, deux options complémentaires existent :

# 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

*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

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 terminé avec succès, ce qui permet à la fois 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 du run précédent, donc un build qui passe 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 :

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

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

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 :

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

Puis exécutez :

act workflow_dispatch -e event.json

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

#!/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 permet de vérifier localement avant le premier push.

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@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false
      - name: Lint
        run: echo "Linting..."

  test:
    runs-on: ubuntu-24.04
    needs: lint
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        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@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false
      - name: Build
        run: echo "Building..."

# Visualiser la structure
act -g

 ╭──────╮
 │ 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 donc par vérifier docker info et l'image effectivement utilisée, affichée 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 : `-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

# 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 90 % des usages quotidiens. Les suivantes servent quand quelque chose ne se passe pas comme prévu ou quand vous testez un cas particulier. Retenez surtout l'ordre : act -l pour vérifier ce qui est détecté, act -n pour valider la structure sans 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-latest`	Définir l'image
`act --container-architecture linux/amd64`	Forcer l'architecture (Mac M1/M2)

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

À 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

Pour aller plus loin

Formation Dagger : Une autre voie pour exécuter le même pipeline en local et en CI, quand les limites de act deviennent gênantes.
pre-commit : Placer les contrôles rapides avant le commit et réserver act aux vérifications lourdes.
Docker de A à Z : Maîtriser le moteur de conteneurs dont act dépend pour chaque job simulé.

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.

Définition

act est un outil en ligne de commande qui exécute vos workflows GitHub Actions localement sur votre machine, sans avoir besoin de pousser le code sur GitHub.

Comment ça fonctionne ?

act lit vos fichiers YAML dans .github/workflows/
Il crée des conteneurs Docker qui imitent les runners GitHub
Il exécute les jobs comme s'ils tournaient sur GitHub

Avantages principaux

Avantage	Description
Itération rapide	Tests en secondes au lieu de minutes
Économie	Pas de consommation de minutes GitHub Actions
Debug local	Logs détaillés, investigation dans les conteneurs
Offline	Fonctionne sans connexion internet (après le pull initial)

Exemple rapide

# Tester le workflow ci.yml
act -W .github/workflows/ci.yml

# Voir ce qui serait exécuté (dry-run)
act -n

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.

Comparaison

Critère	act (local)	GitHub Actions (cloud)
Environnement	Conteneurs Docker locaux	VMs GitHub-hosted
Images	~500 Mo (Medium)	~18 Go (complète)
Latence	Secondes	Minutes (queue + boot)
API GitHub	Limitée	Complète
Secrets	Fichier `.secrets`	GitHub Secrets
Cache	Local uniquement	Partagé entre runs
Coût	Gratuit (Docker local)	Minutes facturées

Ce que act supporte bien

✅ Syntaxe YAML et structure des workflows
✅ Steps avec run: et uses:
✅ Variables d'environnement et secrets
✅ Matrices de build
✅ Actions du Marketplace (la plupart)

Ce que act ne supporte pas (ou partiellement)

❌ Événements schedule, deployment, page_build
⚠️ actions/cache (stockage local uniquement)
⚠️ actions/upload-artifact (fichiers locaux, pas d'API)
❌ Accès complet à l'API GitHub
❌ Services Docker complexes

Recommandation

Utilisez act pour : développement, tests rapides, debug
Validez toujours sur GitHub : avant merge en production

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.

Prérequis

Docker doit être installé et en cours d'exécution :

docker version

macOS

brew install act

Linux

Option 1 : Homebrew

brew install act

Option 2 : Script d'installation

curl -sSL https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Option 3 : asdf-vm

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

Windows

Chocolatey

choco install act-cli

Scoop

scoop install act

Vérification

act --version
# act version 0.2.84

Premier lancement

À la première exécution, act demande quelle image utiliser :

Image	Taille	Usage
Micro	~200 Mo	Tests basiques
Medium	~500 Mo	Recommandé pour la plupart des cas
Large	~18 Go	Compatibilité maximale

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.

Méthode 1 : Fichier .secrets (recommandé)

Créez un fichier .secrets à la racine :

# .secrets
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
NPM_TOKEN=npm_xxxxxxxxxx
AWS_ACCESS_KEY_ID=AKIAXXXXXXXX
AWS_SECRET_ACCESS_KEY=xxxxxxxxxx

Utilisation :

act --secret-file .secrets

Méthode 2 : Ligne de commande

act -s GITHUB_TOKEN=ghp_xxxx -s MY_SECRET=valeur

Méthode 3 : Variables d'environnement

export GITHUB_TOKEN=ghp_xxxx
act

Variables non sensibles (.vars)

Pour ${{ vars.X }} :

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

act --var-file .vars

Configuration permanente (.actrc)

# .actrc
--secret-file .secrets
--var-file .vars

Sécurité

Ajoutez .secrets au .gitignore :

echo ".secrets" >> .gitignore

Ne jamais commiter de secrets !

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.

Images disponibles

Image	Taille	Compatibilité	Usage
Micro	~200 Mo	Limitée	Tests syntaxe uniquement
Medium	~500 Mo	Bonne	Recommandé pour la plupart
Large	~18 Go	Excellente	Workflows complexes

Configuration dans .actrc

# .actrc
-P ubuntu-24.04=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
-P ubuntu-latest=catthehacker/ubuntu:act-latest

Images catthehacker (recommandées)

# Medium (par défaut)
catthehacker/ubuntu:act-latest
catthehacker/ubuntu:act-22.04

# Full (plus complète)
catthehacker/ubuntu:full-latest
catthehacker/ubuntu:full-22.04

Mac M1/M2 (Apple Silicon)

Certaines images ne fonctionnent pas en ARM natif :

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

À ajouter dans .actrc pour éviter de le répéter.

Ligne de commande

# Utiliser une image spécifique pour ce run
act -P ubuntu-24.04=catthehacker/ubuntu:full-latest

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.

Événements supportés

# Push (par défaut)
act
act push

# Pull request
act pull_request

# Workflow manuel
act workflow_dispatch

# Release
act release

# Issue
act issues

# Pull request review
act pull_request_review

Lister les workflows

# Tous les workflows et jobs
act -l

# Pour un événement spécifique
act -l push
act -l pull_request

workflow_dispatch avec inputs

Pour un workflow avec inputs :

on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [dev, staging, prod]

Créez event.json :

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

Exécutez :

act workflow_dispatch -e event.json

Événements NON supportés

❌ schedule (cron)
❌ deployment
❌ page_build
❌ repository_dispatch (partiellement)

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.

Niveaux de verbosité

# Normal
act

# Verbose (logs détaillés)
act -v

# Très verbose (debug complet)
act -vv

Dry-run (sans exécution)

# Voir ce qui serait exécuté
act -n

Utile pour valider la syntaxe avant une vraie exécution.

Garder le conteneur pour investigation

# Le conteneur reste après l'exécution
act --reuse

# Puis vous pouvez y accéder
docker exec -it <container_id> bash

Cibler un job spécifique

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

# Job spécifique d'un workflow
act -W .github/workflows/ci.yml -j build

Workflow de debug recommandé

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

# 2. Dry-run
act -n

# 3. Exécution avec logs
act -v

# 4. Si échec, garder le conteneur
act --reuse -v

Variables de debug GitHub

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

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.

Diagnostic

# Vérifier que Docker tourne
docker info

# Si erreur, démarrer Docker
sudo systemctl start docker  # Linux
# Ou ouvrir Docker Desktop     # macOS/Windows

Cause 1 : Docker n'est pas démarré

Linux :

sudo systemctl start docker
sudo systemctl enable docker  # Démarrage auto

macOS/Windows : Ouvrir Docker Desktop

Cause 2 : Permissions (Linux)

# Ajouter l'utilisateur au groupe docker
sudo usermod -aG docker $USER

# IMPORTANT : se déconnecter et reconnecter
# Ou utiliser newgrp
newgrp docker

# Vérifier
docker info

Cause 3 : Socket Docker inaccessible

# Vérifier le socket
ls -la /var/run/docker.sock

# Doit afficher quelque chose comme :
# srw-rw---- 1 root docker ... /var/run/docker.sock

Cause 4 : Docker Desktop non lancé (macOS/Windows)

Ouvrez l'application Docker Desktop et attendez que l'icône indique "Running".

Test final

docker run hello-world
act --version

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.

Comportement par défaut

act exécute toutes les combinaisons de la matrice :

jobs:
  test:
    strategy:
      matrix:
        node: [18, 20, 22]
        os: [ubuntu-latest]
    # act exécutera 3 jobs (node 18, 20, 22)

Voir les combinaisons

act -l
# Affiche chaque combinaison comme un job séparé

Exécuter une seule combinaison

# Flag -m pour une seule combinaison (la première)
act -j test -m

Matrices avec include/exclude

strategy:
  matrix:
    node: [18, 20]
    include:
      - node: 22
        experimental: true
    exclude:
      - node: 18
        os: windows-latest

act respecte include et exclude.

Limiter les combinaisons (astuce)

Pour tester rapidement, créez un fichier de workflow de test :

# .github/workflows/ci-local.yml
jobs:
  test:
    strategy:
      matrix:
        node: [20]  # Une seule version

act -W .github/workflows/ci-local.yml

Performance

Les matrices volumineuses (ex: 3 OS × 4 versions = 12 jobs) peuvent être longues. Préférez tester une combinaison localement, puis valider la matrice complète sur GitHub.

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.

Workflow de validation complet

# 1. Validation statique (syntaxe, typos, refs)
actionlint .github/workflows/*.yml

# 2. Dry-run (structure, résolution)
act -n

# 3. Exécution réelle
act -v

Ce que chaque outil détecte

Outil	Détecte
actionlint	Syntaxe YAML, typos dans `uses:`, variables invalides, permissions
act -n	Résolution des actions, structure du workflow
act	Erreurs d'exécution, logique, scripts

Hook pre-push automatique

#!/bin/bash
# .git/hooks/pre-push

echo "🔍 Validation des workflows..."

# Étape 1 : actionlint
if ! actionlint .github/workflows/*.yml; then
    echo "❌ Erreurs de syntaxe. Push annulé."
    exit 1
fi

# Étape 2 : act dry-run
if ! act -n -W .github/workflows/ci.yml; then
    echo "❌ Erreurs de structure. Push annulé."
    exit 1
fi

echo "✅ Workflows valides"

Rendre exécutable :

chmod +x .git/hooks/pre-push

Installation actionlint

# macOS/Linux
brew install actionlint

# Go
go install github.com/rhysd/actionlint/cmd/actionlint@latest

Voir le guide complet : actionlint

act : exécuter les workflows GitHub Actions en local

Architecture de act

Ce que vous allez apprendre

Prérequis

Installation

Premier lancement

Utilisation de base

Exécuter le workflow par défaut

Exécuter un workflow spécifique

Exécuter un job spécifique

Simuler différents événements

Lister les workflows disponibles

Visualiser le graphe des dépendances

Gestion des secrets

Fichier .secrets

Secrets en ligne de commande

Variables d'environnement

Configuration avancée

Fichier .actrc

Images Docker personnalisées

Mode verbeux pour le debug

Exécution à sec (dry-run)

Limitations de act

Cas d'usage courants

Debug interactif

Workflow avec matrice

Tester un workflow_dispatch avec inputs

Intégration dans le flux de développement

Script de validation pré-push

Combinaison avec actionlint

Exemple complet

Dépannage

Aide-mémoire (cheatsheet)

Contrôle de connaissances

Contrôle de connaissances

Informations

Profil de compétences

Quoi faire maintenant

À retenir

Pour aller plus loin

Ressources

Questions fréquentes

Définition

Comment ça fonctionne ?

Avantages principaux

Exemple rapide

Comparaison

Ce que act supporte bien

Ce que act ne supporte pas (ou partiellement)

Recommandation

Prérequis

macOS

Linux

Windows

Vérification

Premier lancement

Méthode 1 : Fichier .secrets (recommandé)

Méthode 2 : Ligne de commande

Méthode 3 : Variables d'environnement

Variables non sensibles (.vars)

Configuration permanente (.actrc)

Sécurité

Images disponibles

Configuration dans .actrc

Images catthehacker (recommandées)

Mac M1/M2 (Apple Silicon)

Ligne de commande

Événements supportés

Lister les workflows

workflow_dispatch avec inputs

Événements NON supportés

Niveaux de verbosité

Dry-run (sans exécution)

Garder le conteneur pour investigation

Cibler un job spécifique

Workflow de debug recommandé

Variables de debug GitHub

Diagnostic

Cause 1 : Docker n'est pas démarré

Cause 2 : Permissions (Linux)