Qu'est-ce qu'Act ?

Act est un outil en ligne de commande open source qui vous permet d'exécuter les workflows GitHub Actions en local, sans avoir à pousser votre code sur GitHub pour tester et déboguer vos pipelines CI/CD.

Pour les développeurs qui écrivent régulièrement des workflows GitHub Actions, c'est un gain de temps considérable :

  • Itération rapide : exécutez immédiatement vos workflows en local après chaque modification, sans attendre la file d'attente et l'exécution sur GitHub
  • Économie de ressources : ne consomme pas les minutes GitHub Actions (surtout pour les dépôts privés)
  • Débogage hors ligne : testez vos workflows même sans connexion Internet
  • Tests sécurisés : vérifiez la sécurité de vos workflows dans un environnement isolé, évitant l'exécution accidentelle d'opérations dangereuses

Pourquoi utiliser Act ?

GitHub Actions est une plateforme CI/CD puissante, mais le débogage des workflows présente un inconvénient majeur :

Modifier .github/workflows/test.yml 
→ git commit 
→ git push 
→ Attendre la file d'attente GitHub (peut prendre de quelques minutes à plusieurs heures)
→ Consulter les logs et découvrir une erreur
→ Recommencer tout le processus

Ce cycle est extrêmement chronophage. Avec Act, vous pouvez :

Modifier .github/workflows/test.yml 
→ act -j test    # exécution locale immédiate
→ Analyser la sortie, corriger le problème
→ Relancer, confirmer que tout fonctionne avant de pousser

Le gain d'efficacité est d'au moins 10 fois.

Act comparé aux autres solutions

Fonctionnalité Act Interface web GitHub Simulation Docker Compose
Vitesse d'exécution ⚡ Immédiate en local 🐌 File d'attente nécessaire ⚡ Local mais configuration complexe
Fidélité ✅ Utilise les vraies images runner GitHub Actions ✅ Totalement réel ❌ Nécessite une simulation manuelle
Coût 💰 Gratuit (exécution locale) 💰 Consomme des minutes Actions 💰 Gratuit
Facilité d'utilisation ✅ Une seule commande ✅ Interface graphique ❌ Configuration fastidieuse
Support hors ligne ✅ Totalement hors ligne ❌ Nécessite une connexion ✅ Possible hors ligne

Installation d'Act

macOS (Homebrew)

BASH 
brew install act

Linux

Ubuntu/Debian :

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

Arch Linux :

BASH 
yay -S act
# ou
paru -S act

Windows

Chocolatey :

POWERSHELL 
choco install act-cli

Scoop :

POWERSHELL 
scoop install act

Vérification de l'installation

BASH 
act --version
# Résultat similaire : act version 0.2.x

Premiers pas : exécuter votre premier workflow

Prérequis

Assurez-vous que votre projet contient un répertoire .github/workflows/ à la racine, avec au moins un fichier workflow (.yml ou .yaml).

Lister les workflows disponibles

BASH 
cd /path/to/your/project
act -l

Exemple de sortie :

Stage  Job ID  Nom du job  Nom du workflow  Fichier workflow  Événements
0      test    Test        CI               ci.yml            push,pull_request
0      build   Build       CI               ci.yml            push,pull_request

Exécuter un job spécifique

BASH 
# Exécuter le job nommé test
act -j test

# Exécuter tous les jobs
act

# Exécuter un workflow déclenché par un événement spécifique (ex. pull_request)
act pull_request

Remarques pour la première exécution

Lors de la première exécution, Act télécharge les images Docker nécessaires (généralement catthehacker/ubuntu:act-latest), ce qui peut prendre quelques minutes. Les exécutions suivantes utilisent le cache et sont plus rapides.

INFO[0000] Utilisation de l'hôte Docker 'unix:///var/run/docker.sock'
INFO[0000] Téléchargement de l'image 'catthehacker/ubuntu:act-latest'
...

Utilisation avancée

1. Utiliser différentes images runner

Act utilise par défaut une image Ubuntu, mais vous pouvez spécifier différentes plateformes avec le paramètre -P :

BASH 
# Utiliser Ubuntu 22.04
act -P ubuntu-latest=catthehacker/ubuntu:act-22.04

# Utiliser Ubuntu 20.04
act -P ubuntu-latest=catthehacker/ubuntu:act-20.04

# Utiliser une image légère (plus rapide, mais fonctionnalités limitées)
act -P ubuntu-latest=node:16-buster-slim

2. Transmettre des secrets et variables d'environnement

De nombreux workflows dépendent de secrets (clés API, tokens). Vous pouvez les transmettre via un fichier .env ou en ligne de commande :

Méthode 1 : Utiliser un fichier .env

Créez un fichier .env à la racine de votre projet :

BASH 
MY_API_KEY=votre_clé_secrète
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Puis exécutez :

BASH 
act --secret-file .env

Méthode 2 : Transmission directe en ligne de commande

BASH 
act -s MY_API_KEY=votre_clé_secrète -s GITHUB_TOKEN=ghp_xxxxxxxxxxxx

3. Exécution parallèle de plusieurs jobs

Si votre workflow contient plusieurs jobs indépendants, utilisez --parallel pour accélérer l'exécution :

BASH 
act --parallel

4. Mode simulation (Dry Run)

Affiche uniquement les étapes qui seront exécutées, sans les lancer réellement :

BASH 
act -n

5. Répertoire de travail personnalisé

Si votre workflow dépend d'une structure de répertoires spécifique, vous pouvez monter un volume :

BASH 
act --bind

Cela monte le répertoire courant dans le conteneur, permettant aux modifications de fichiers d'être prises en compte en temps réel.

Cas pratiques

Cas 1 : Déboguer le CI d'un projet Node.js

Supposons que vous ayez un projet Node.js avec le workflow suivant :

YAML 
# .github/workflows/nodejs.yml
name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

Exécution en local :

BASH 
act -j test

Si les tests échouent, Act affiche l'intégralité des logs, facilitant l'identification du problème.

Cas 2 : Tester une matrice de versions Python multiples

YAML 
# .github/workflows/python.yml
name: Python Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests
        run: pytest

Exécuter les tests pour toutes les versions Python :

BASH 
act -j test

Act parcourt automatiquement toutes les combinaisons de la matrice et les exécute successivement.

Cas 3 : Déboguer une construction Docker

YAML 
# .github/workflows/docker.yml
name: Build Docker Image

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Run tests in container
        run: docker run myapp:${{ github.sha }} npm test

Avant l'exécution en local, assurez-vous que le daemon Docker est actif :

BASH 
# Vérifier que Docker est disponible
docker info

# Exécuter le workflow
act -j build

Résolution des problèmes courants

Problème 1 : Erreur de permissions

Symptôme : permission denied while trying to connect to the Docker daemon socket

Solution :

BASH 
# Ajouter l'utilisateur actuel au groupe docker
sudo usermod -aG docker $USER
# Se reconnecter ou exécuter newgrp docker

Ou utiliser sudo pour exécuter Act (non recommandé) :

BASH 
sudo act

Problème 2 : Mémoire insuffisante

Symptôme : OOM (Out of Memory) lors de l'exécution de workflows volumineux

Solution : Limiter le nombre de jobs concurrents

BASH 
act --max-parallel 1

Problème 3 : Action introuvable

Symptôme : unable to find action 'actions/checkout@v4'

Solution : Act doit télécharger les actions depuis GitHub, assurez-vous que la connexion réseau fonctionne. Pour les actions privées, configurez GITHUB_TOKEN.

Problème 4 : Variables d'environnement non effectives

Symptôme : Les variables d'environnement référencées dans le workflow sont vides

Solution : Assurez-vous d'avoir correctement transmis les variables via --secret-file ou -s, et référencez-les dans le workflow avec ${{ env.VAR_NAME }} ou ${{ secrets.VAR_NAME }}.

Bonnes pratiques

  1. Toujours tester en local avant de pousser : prenez l'habitude de valider vos workflows avec Act après chaque modification
  2. Utiliser un fichier .env pour gérer les secrets : ne codez jamais en dur les informations sensibles, ajoutez .env à .gitignore
  3. Mettre régulièrement Act à jour : brew upgrade act ou téléchargez la dernière version
  4. Combiner avec VS Code : installez l'extension GitHub Actions pour prévisualiser les workflows directement dans l'éditeur
  5. Conserver Act comme étape optionnelle dans le CI : rappelez aux contributeurs de tester en local dans le modèle de PR

Conclusion

Act est un outil indispensable pour les développeurs GitHub Actions. Il réduit un cycle de débogage qui prenait auparavant plusieurs minutes, voire plusieurs heures, à quelques secondes seulement. Que ce soit pour des workflows de tests unitaires simples ou des pipelines de déploiement multi-étapes complexes, Act vous permet de valider rapidement en local.

Récapitulatif des avantages clés : - ⚡ Itération rapide : exécution locale immédiate, sans attente de file d'attente GitHub - 💰 Économie de coûts : ne consomme pas les minutes GitHub Actions - 🔒 Isolation sécurisée : exécution en conteneur, sans impact sur l'environnement hôte - 🛠️ Environnement réel : utilise les mêmes images runner que GitHub, résultats fiables

Si vous écrivez ou maintenez régulièrement des workflows GitHub Actions, il est fortement recommandé d'ajouter Act à votre boîte à outils.

Liens utiles : - Dépôt GitHub d'Act - Documentation officielle d'Act - Documentation GitHub Actions