Comment exécuter vos GitHub Actions localement avec Act

Les GitHub Actions ont révolutionné la façon dont les développeurs automatisent les flux de travail au sein de leurs référentiels. Des pipelines d'intégration continue et de déploiement continu (CI/CD) à l'automatisation de l'étiquetage des problèmes et de la génération de notes de version, Actions offre un moyen puissant et intégré de gérer le cycle de vie du développement logiciel directement dans GitHub.

Cependant, le développement et le test de ces flux de travail peuvent parfois sembler fastidieux. Le cycle traditionnel implique :

Apporter des modifications à vos fichiers de flux de travail (généralement situés dans .github/workflows/).
Valider ces modifications.
Les pousser vers votre référentiel GitHub.
Attendre que les runners de GitHub prennent en charge le travail et l'exécutent.
Analyser les journaux sur le site Web de GitHub pour voir si vos modifications ont fonctionné ou si elles ont introduit des erreurs.

Ce processus, en particulier la partie attente et le changement de contexte entre votre éditeur local et l'interface utilisateur de GitHub, peut considérablement ralentir le développement, en particulier lors de l'itération sur des flux de travail complexes ou du débogage de problèmes délicats. Et si vous pouviez tester vos Actions avant de les pousser ?

C'est précisément là qu'act entre en jeu. Comme le suggère son slogan, "Think globally, act locally". act est un outil de ligne de commande open source conçu pour exécuter vos flux de travail GitHub Actions localement à l'aide de conteneurs Docker. Il simule l'environnement fourni par GitHub Actions, vous permettant de tester et d'itérer rapidement sur vos flux de travail sans avoir besoin de valider et de pousser chaque modification mineure.

💡

Vous voulez un excellent outil de test d'API qui génère une belle documentation API ?

Vous voulez une plateforme intégrée, tout-en-un, pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !

button

Pourquoi exécuter GitHub Actions localement avec `act` ?

Les avantages d'intégrer act dans votre flux de travail de développement sont importants :

Retour d'information rapide : C'est le principal avantage. Au lieu du cycle commit-push-wait-debug, vous pouvez exécuter votre flux de travail immédiatement après avoir apporté une modification localement. Obtenez des commentaires en quelques secondes ou minutes, et non en minutes ou dizaines de minutes. Cela accélère considérablement le processus de développement et de débogage de vos fichiers .github/workflows/.
Exécuteur de tâches local : De nombreux projets utilisent des outils comme make, npm scripts ou des scripts shell personnalisés pour définir des tâches de développement courantes (construction, test, linting, etc.). act vous permet de consolider ces tâches. Vous pouvez définir votre build, vos tests et d'autres processus en tant que tâches GitHub Actions, puis utiliser act pour exécuter ces mêmes tâches localement à des fins de développement. Cela réduit la duplication et assure la cohérence entre votre environnement de développement local et votre pipeline CI/CD. Vous définissez les tâches une fois dans vos fichiers de flux de travail, et elles s'exécutent de la même manière (ou très similaire) partout.
Développement hors ligne : Testez la syntaxe et la logique de base du flux de travail même sans connexion Internet constante (bien que les téléchargements d'images initiaux et certaines actions puissent nécessiter une connectivité).
Économies de coûts : Bien que GitHub fournisse une offre gratuite généreuse pour les référentiels publics et des prix raisonnables pour les référentiels privés, l'exécution répétée de flux de travail complexes ou longs pendant le développement peut consommer des minutes de runner. Les tests locaux évitent cette utilisation.
Puissance de débogage : Le débogage des Actions ayant échoué sur GitHub implique souvent d'ajouter une journalisation supplémentaire, de pousser et d'attendre. Avec act, vous pouvez inspecter l'environnement local, monter des volumes et potentiellement utiliser des techniques de débogage plus avancées dans les conteneurs Docker qu'il lance.

Comment `act` fonctionne-t-il ?

Comprendre le mécanisme derrière act aide à l'utiliser efficacement et à résoudre les problèmes potentiels. Voici une ventilation de son fonctionnement :

Analyse du flux de travail : Lorsque vous exécutez la commande act dans le répertoire racine de votre référentiel, elle analyse le répertoire .github/workflows/ pour vos fichiers YAML de flux de travail.
Simulation du déclencheur d'événement : Par défaut, act simule un événement push, mais vous pouvez spécifier d'autres événements comme pull_request, workflow_dispatch, etc. Il détermine quels flux de travail et quelles tâches doivent s'exécuter en fonction de l'événement spécifié et des déclencheurs on: définis dans vos fichiers de flux de travail.
Analyse des dépendances : act analyse les dépendances entre les tâches d'un flux de travail (à l'aide du mot-clé needs:) pour déterminer l'ordre d'exécution correct.
Gestion des images Docker : Pour chaque tâche, act identifie l'environnement du runner spécifié (par exemple, runs-on: ubuntu-latest). Il le mappe ensuite à une image Docker spécifique. act utilise l'API Docker pour :

Extraire les images : Télécharger les images de runner requises et toutes les images Docker utilisées par les actions de conteneur (uses: docker://...). Par défaut, il extrait les images à chaque exécution, sauf configuration contraire.
Construire des images (si nécessaire) : Si une action pointe vers un Dockerfile local (uses: ./path/to/action), act peut construire l'image Docker localement.

Exécution du conteneur : act utilise l'API Docker pour créer et exécuter des conteneurs pour chaque étape d'une tâche. Il configure ces conteneurs pour imiter au plus près l'environnement GitHub Actions :

Variables d'environnement : Les variables d'environnement standard de GitHub Actions (comme GITHUB_SHA, GITHUB_REF, GITHUB_REPOSITORY, CI, etc.) sont injectées.
Système de fichiers : Le code du référentiel est monté dans le répertoire de l'espace de travail du conteneur (/github/workspace). Les fichiers générés par les étapes sont conservés dans le conteneur pour les étapes suivantes.
Mise en réseau : Les conteneurs sont généralement exécutés sur un réseau de pont Docker, ce qui permet la communication si nécessaire (bien que les spécificités de la mise en réseau puissent différer de l'environnement de GitHub).

Diffusion de journaux : act diffuse les journaux des conteneurs en cours d'exécution directement dans votre terminal, fournissant un retour d'information en temps réel sur la progression de l'exécution et les éventuelles erreurs.

Essentiellement, act orchestre les conteneurs Docker locaux pour reproduire le flux d'exécution et l'environnement de vos flux de travail GitHub Actions.

Conditions préalables : Installation de Docker

La dépendance principale pour act est Docker. act exploite le moteur Docker pour créer les environnements isolés nécessaires à l'exécution des étapes de votre flux de travail. Avant d'installer act, vous devez avoir une installation Docker fonctionnelle sur votre système.

Installer Docker : Suivez les instructions officielles pour votre système d'exploitation :
macOS : Docker Desktop pour Mac
Windows : Docker Desktop pour Windows (Nécessite WSL 2 ou Hyper-V)
Linux : Suivez les instructions spécifiques à votre distribution (par exemple, Ubuntu, Fedora, Debian, etc.). Assurez-vous d'ajouter votre utilisateur au groupe docker pour exécuter les commandes Docker sans sudo.
Vérifier Docker : Après l'installation, ouvrez votre terminal et exécutez docker run hello-world. Cette commande télécharge une petite image de test et l'exécute dans un conteneur. Si elle s'exécute avec succès, votre configuration Docker est prête.

Installation de `act`

Une fois Docker en cours d'exécution, vous pouvez installer act. Il existe plusieurs façons de le faire, en fonction de votre système d'exploitation et de vos préférences.

1. Homebrew (macOS et Linux)

Si vous utilisez le gestionnaire de paquets Homebrew, l'installation est simple :

brew install act

Cela installe la dernière version stable. Si vous souhaitez la toute dernière version de développement (qui peut nécessiter un compilateur), vous pouvez utiliser :

brew install act --HEAD

2. Extension GitHub CLI (macOS, Windows, Linux)

Si vous utilisez déjà l'interface de ligne de commande GitHub (gh), vous pouvez installer act en tant qu'extension :

gh extension install nektos/gh-act

Après l'installation, vous appelez act via la commande gh :

gh act          # Au lieu de simplement 'act'
gh act -l
gh act pull_request

3. Chocolatey (Windows)

Pour les utilisateurs du gestionnaire de paquets Chocolatey sur Windows :

choco install act-cli

(Remarque : certaines sources peuvent répertorier act au lieu de act-cli. Vérifiez le dernier nom de package sur le référentiel de la communauté Chocolatey si vous rencontrez des problèmes.)

4. Scoop (Windows)

Pour les utilisateurs du gestionnaire de paquets Scoop sur Windows :

scoop install act

5. WinGet (Windows)

Pour les utilisateurs du gestionnaire de paquets Windows (winget) :

winget install nektos.act

6. Installateur de script Linux

Un script de commodité est disponible pour les distributions Linux sans accès facile via les gestionnaires de paquets :

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

(Remarque : soyez toujours prudent lorsque vous pipez des scripts directement dans sudo. Examinez d'abord le contenu du script si vous avez des problèmes de sécurité.)

7. Autres méthodes (Arch, COPR, MacPorts, Nix)

Les instructions d'installation pour d'autres gestionnaires de paquets comme pacman (Arch), COPR (Fedora), MacPorts et Nix sont disponibles dans la documentation officielle de act :

Vérification :

Après l'installation, ouvrez une nouvelle fenêtre de terminal et exécutez :

act --version
# ou si vous utilisez l'extension gh :
gh act --version

Cela devrait afficher la version installée de act, confirmant que l'installation a réussi.

Configuration initiale : Images de runner

La première fois que vous exécutez act dans un répertoire de projet, il peut vous inviter à choisir une taille d'image de runner par défaut. GitHub Actions propose des runners avec des ressources et des logiciels préinstallés variables. act essaie d'imiter cela en utilisant différentes images Docker de base.

On vous présentera généralement un choix comme celui-ci :

? Veuillez choisir l'image par défaut que vous souhaitez utiliser avec act :

  - Micro : Image minimale avec prise en charge de nodejs (~200 Mo) docker.io/node:16-buster-slim
  - Medium : Image Act avec des outils de base (~500 Mo) ghcr.io/catthehacker/ubuntu:act-latest
  - Large : Image de runner Github Actions (~17 Go) ghcr.io/catthehacker/ubuntu:full-latest

Image par défaut ? [Medium] :

Micro : Basé sur les images slim officielles de Node.js (comme node:16-buster-slim ou node:16-bullseye-slim). Très petit et rapide à télécharger, mais ne contient que Node.js et des bibliothèques système minimales. Convient si vos actions n'ont besoin que de Node.js ou installent toutes leurs dépendances elles-mêmes.
Medium : Fourni par l'utilisateur catthehacker (par exemple, catthehacker/ubuntu:act-latest, catthehacker/ubuntu:act-22.04). Ces images incluent des outils plus courants trouvés sur les runners GitHub, mais sont encore relativement légères (environ 500 Mo). Il s'agit souvent du paramètre par défaut recommandé, car il équilibre les fonctionnalités et la taille.
Large : Également de catthehacker (par exemple, catthehacker/ubuntu:full-latest, catthehacker/ubuntu:full-22.04). Ceux-ci sont créés à partir de vidages du système de fichiers des runners réellement hébergés par GitHub et contiennent presque tous les logiciels préinstallés. Ils offrent la plus grande compatibilité, mais sont très volumineux (souvent > 17 Go), ce qui entraîne de longs temps de téléchargement initiaux et une utilisation importante de l'espace disque.

Recommandation : Commencez par l'image Medium. Elle offre un bon équilibre et fonctionne pour de nombreux cas d'utilisation courants. Si vous rencontrez des problèmes en raison de logiciels manquants, vous pouvez soit installer le logiciel dans les étapes de votre flux de travail, soit passer à l'utilisation de l'image Large pour ce runner spécifique (plus d'informations à ce sujet plus tard).

act enregistre votre choix dans un fichier de configuration (~/.actrc). Vous pouvez modifier le paramètre par défaut ultérieurement en modifiant ce fichier ou en réexécutant act dans un répertoire où il doit être configuré.

Utilisation principale de `act` : Exécution de vos flux de travail

Une fois installé et configuré, l'utilisation de act est relativement simple. Accédez au répertoire racine de votre projet (celui contenant le dossier .github) dans votre terminal.

1. Exécuter l'événement par défaut (push)

La commande la plus simple exécute les flux de travail déclenchés par l'événement push par défaut :

act
# ou
gh act

act analysera vos flux de travail, identifiera les tâches déclenchées on: push, extraira les images Docker nécessaires (si elles ne sont pas déjà mises en cache) et exécutera les tâches.

2. Lister les flux de travail et les tâches disponibles

Pour voir quels flux de travail et quelles tâches act reconnaît et exécuterait pour l'événement par défaut :

act -l
# ou
gh act -l

Cela affiche une liste comme celle-ci :

Étape  ID de la tâche  Nom de la tâche  Nom du flux de travail  Fichier du flux de travail  Événements
0      build         Build         CI Pipeline    ci.yaml        push
1      test          Test          CI Pipeline    ci.yaml        push
1      lint          Lint          Code Quality   codeql.yaml    push,pull_request

3. Exécuter une tâche spécifique

Si vous souhaitez uniquement tester une seule tâche à partir d'un flux de travail, utilisez l'indicateur -j suivi de l'ID de la tâche (à partir de la sortie act -l) :

act -j build
# ou
gh act -j build

4. Déclencher un événement spécifique

Les flux de travail se déclenchent souvent sur des événements autres que push. Vous pouvez simuler ces événements en fournissant le nom de l'événement en tant qu'argument à act :

# Simuler un événement de demande d'extraction
act pull_request

# Simuler un événement workflow_dispatch (déclencheur manuel)
act workflow_dispatch

# Simuler un événement d'horaire
act schedule

# Simuler un événement de publication
act release -e event.json # Fournir les détails de la charge utile de l'événement si nécessaire

act n'exécutera que les flux de travail et les tâches configurés pour s'exécuter on: l'événement spécifié.

5. Transmission des entrées pour workflow_dispatch

Les flux de travail déclenchés par workflow_dispatch peuvent accepter des entrées. Vous pouvez les fournir à l'aide de l'indicateur --input ou -i :

# En supposant que votre flux de travail a une entrée nommée 'environment'
act workflow_dispatch --input environment=staging

6. Gestion des secrets

Les flux de travail GitHub Actions s'appuient souvent sur des secrets (comme des clés API ou des jetons). act n'accède pas automatiquement à vos secrets GitHub. Vous devez les fournir localement.

Invite interactive : Utilisez l'indicateur -s. act vous invitera à saisir la valeur de chaque secret défini dans votre flux de travail :

act -s MY_SECRET_TOKEN -s ANOTHER_SECRET

Sinon, juste act -s vous invitera à saisir tous les secrets.

Variables d'environnement : Les secrets sont souvent transmis en tant que variables d'environnement préfixées par SECRET_. Vous pouvez les définir dans votre shell avant d'exécuter act :

export SECRET_MY_SECRET_TOKEN="your_value"
act

Fichier de secrets : Créez un fichier (par exemple, .secrets) avec des paires KEY=VALUE :

MY_SECRET_TOKEN=your_value
ANOTHER_SECRET=another_value

Exécutez ensuite act avec l'indicateur --secret-file :

act --secret-file .secrets

(Assurez-vous que ce fichier est ajouté à votre .gitignore pour éviter de valider les secrets !)

7. Gestion des variables et des variables d'environnement

Variables de flux de travail : Vous pouvez fournir des valeurs pour les variables définies au niveau du flux de travail (contexte vars:, bien que la prise en charge complète du contexte vars dans act puisse être limitée) à l'aide de l'indicateur --var ou d'un --var-file, similaire aux secrets.
Variables d'environnement : Pour définir des variables d'environnement personnalisées pour l'exécution du flux de travail, utilisez l'indicateur --env ou un --env-file.

act --env NODE_ENV=development --env CUSTOM_FLAG=true
act --env-file .env_vars

Gestion des environnements et des images de runner

Bien que les images de runner par défaut (Micro, Medium, Large) couvrent de nombreux scénarios, vous avez souvent besoin de plus de contrôle.

1. Limitations des images par défaut

N'oubliez pas que les images de runner act par défaut (en particulier Micro et Medium) ne sont pas identiques aux environnements fournis par GitHub. Elles peuvent manquer d'outils, de bibliothèques ou de services système spécifiques (comme systemd) que votre flux de travail attend. Les images Large offrent une plus grande fidélité, mais présentent l'inconvénient d'une taille importante.

2. Spécification d'images alternatives avec -P

Si une tâche nécessite un environnement ou un ensemble d'outils spécifique non présent dans l'image par défaut, vous pouvez indiquer à act d'utiliser une image Docker différente pour une plate-forme spécifique à l'aide de l'indicateur -P (plate-forme).

Le format est -P <platform>=<docker-image>.

<platform> : L'étiquette utilisée dans la directive runs-on: de votre flux de travail (par exemple, ubuntu-latest, ubuntu-22.04, ubuntu-20.04).
<docker-image> : Le nom complet de l'image Docker à utiliser (par exemple, node:18, python:3.10-slim, mcr.microsoft.com/devcontainers/base:ubuntu).

Exemples :

# Utiliser l'image Large spécifiquement pour les tâches s'exécutant sur ubuntu-22.04
act -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:full-22.04

# Utiliser une version spécifique de Node.js pour les tâches ubuntu-latest
act -P ubuntu-latest=node:18-bullseye

# Utiliser une image plus complète de nektos/act-environments (très volumineuse !)
# AVERTISSEMENT : nektos/act-environments-ubuntu:18.04 est > 18 Go
act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04

# Spécifier plusieurs plates-formes si votre flux de travail les utilise
act -P ubuntu-20.04=node:16-buster -P ubuntu-22.04=node:18-bullseye

3. Utilisation d'images de runner locales (--pull=false)

Par défaut, act essaie d'extraire la dernière version de l'image Docker spécifiée à chaque exécution. Si vous avez créé une image de runner personnalisée localement ou si vous souhaitez vous assurer que vous utilisez la version exacte que vous avez mise en cache, vous pouvez désactiver ce comportement :

act --pull=false
# ou potentiellement utiliser le mode hors ligne
act --action-offline-mode

Cela indique à act d'utiliser l'image disponible localement si elle est présente et de n'essayer de l'extraire que si elle est manquante.

4. Exécution native sur l'hôte (-self-hosted)

Pour les flux de travail ciblant macOS ou Windows (runs-on: macos-latest ou runs-on: windows-latest), si vous exécutez act sur le même système d'exploitation hôte, vous pouvez indiquer à act de ne pas utiliser un conteneur Docker pour le runner lui-même. Au lieu de cela, il exécutera les étapes directement sur votre machine hôte. Cela peut être utile si la compatibilité Docker est un problème ou si vous avez besoin d'un accès direct aux ressources de l'hôte.

# Exécuter les tâches macos-latest directement sur votre hôte Mac
act -P macos-latest=-self-hosted

# Exécuter les tâches windows-latest directement sur votre hôte Windows
act -P windows-latest=-self-hosted

Attention : L'exécution directe sur l'hôte contourne l'isolation fournie par Docker. Les étapes du flux de travail auront accès à votre système de fichiers et pourront potentiellement modifier votre environnement hôte. Utilisez cette option avec précaution. Les étapes de la tâche qui utilisent explicitement des conteneurs Docker (comme les conteneurs de service ou les actions de conteneur) utiliseront toujours Docker.

Limitations et considérations

Bien que act soit incroyablement utile, il est important de connaître ses limites :

Pas une réplique parfaite : act simule l'environnement GitHub Actions, mais n'est pas identique. Il existe des différences en matière de mise en réseau, de services système disponibles (par exemple, pas de systemd dans les conteneurs Docker facilement), de ressources matérielles spécifiques et de l'ensemble exact d'outils préinstallés (sauf si vous utilisez les très grandes images de runner). Certains flux de travail, en particulier les flux de travail complexes interagissant fortement avec le système d'exploitation sous-jacent ou des fonctionnalités GitHub spécifiques, peuvent se comporter différemment dans act par rapport à GitHub.
Différences de contexte : Certaines parties du contexte github peuvent être incomplètes ou contenir des valeurs par défaut/fictives lorsqu'elles sont exécutées localement. Le contexte secrets a toujours besoin d'une entrée explicite. La prise en charge du contexte vars peut également présenter des limitations par rapport à l'environnement GitHub en direct.
Concurrence : act exécute généralement les tâches de manière séquentielle en fonction de leurs dépendances needs. Il ne reproduit pas entièrement la capacité de GitHub à exécuter des tâches indépendantes simultanément à l'aide de stratégies de matrice sur plusieurs runners (bien que act prenne en charge l'exécution de tâches de matrice, elles s'exécutent généralement de manière séquentielle localement).
Services hébergés : Des fonctionnalités telles que la mise en cache (actions/cache) peuvent fonctionner différemment ou nécessiter une configuration spécifique localement par rapport au service de mise en cache intégré de GitHub. Les conteneurs de service définis dans les flux de travail devraient fonctionner, car act utilise également Docker pour ceux-ci.
Disponibilité de la plate-forme : Vous ne pouvez exécuter des tâches basées sur Linux dans Docker que sur n'importe quel hôte pris en charge par Docker (Mac, Windows, Linux). Pour exécuter des tâches macos-latest, vous avez idéalement besoin de act sur macOS (ou utilisez l'indicateur -self-hosted sur macOS). De même, les tâches windows-latest nécessitent généralement act sur Windows (ou -self-hosted sur Windows). Bien que Docker puisse exécuter des conteneurs Windows sur Windows, l'objectif principal et la prise en charge la plus stable de act concernent les conteneurs Linux.

Recommandation : Utilisez act pour le développement rapide, la vérification de la syntaxe, les tests de logique de base et l'itération sur des tâches ou des étapes individuelles. Effectuez toujours une validation finale en exécutant vos flux de travail sur GitHub lui-même avant de fusionner les modifications critiques, en particulier pour les pipelines de déploiement. Consultez la documentation officielle de act pour la matrice de prise en charge détaillée et les problèmes connus.

Conclusion

Tester GitHub Actions localement est un important facteur de productivité, transformant le cycle de débogage potentiellement lent et fastidieux en un processus rapide et itératif. L'outil CLI act fournit un moyen robuste et flexible d'y parvenir en tirant parti de Docker pour simuler l'environnement du runner GitHub Actions sur votre machine locale.

En intégrant act dans votre flux de travail, vous gagnez :

Des boucles de rétroaction plus rapides.
Une dépendance réduite à la poussée vers GitHub pour les tests.
La possibilité d'utiliser vos définitions Actions comme un exécuteur de tâches local.
Des capacités de débogage améliorées.

Bien qu'il présente des limites et ne soit pas un remplacement parfait 1:1 de l'environnement GitHub en direct, act couvre un vaste éventail de cas d'utilisation et réduit considérablement les frictions impliquées dans le développement de flux de travail GitHub Actions fiables et efficaces. Installez-le, essayez d'exécuter vos flux de travail existants localement et découvrez les avantages de penser globalement tout en agissant localement.

💡