Comment exécuter GitHub Actions et GitLab CI localement avant de pousser

Vous pouvez exécuter GitHub Actions sur votre propre ordinateur avec `act` et GitLab CI avec gitlab-ci-local : tous deux lisent votre fichier de pipeline et démarrent chaque tâche dans un conteneur Docker. Installez Docker, installez le programme d'exécution, puis exécutez act -j test ou gitlab-ci-local test à partir du dossier du référentiel. Une tâche en échec échoue désormais en quelques secondes sur votre machine au lieu d'après une poussée et une attente d'un exécuteur hébergé.

Ce guide couvre ce qu'il faut installer sur macOS, Windows et Linux, les commandes pour les deux exécuteurs, un exemple de flux de travail que vous pouvez copier, les limites des exécutions locales et les erreurs rencontrées en premier. La procédure pas à pas utilise GitTree, le client Git que nous créons : sa page Pipelines locaux vérifie ce que vous avez installé, écrit un exemple de fichier et prépare la commande exacte pour vous. Les pipelines locaux font partie du forfait gratuit de GitTree et ne nécessitent aucun compte d'hébergement.

Pourquoi exécuter des pipelines CI localement ?

Chaque modification apportée à un fichier de workflow est un code que vous ne pouvez pas tester tant qu'il n'est pas exécuté. Sans coureur local, la boucle est la suivante : modifier le YAML, valider, pousser, attendre un coureur, lire le journal, répéter. Chaque tour coûte des minutes et laisse une trace de commits comme « réessayer ». Une exécution locale raccourcit la boucle à quelques secondes et maintient l'historique propre.

Ce dont vous avez besoin : Docker plus un coureur

Les deux exécuteurs démarrent chaque tâche dans un conteneur, donc un moteur Docker doit être installé et exécuté : Docker Desktop, OrbStack ou Colima sur macOS, Docker Desktop sur Windows, Docker Engine ou Docker Desktop sur Linux. Ensuite, installez le runner pour votre fichier.

gitlab-ci-local nécessite Node.js 18 ou version ultérieure lorsque vous l'installez avec npm. Vérifiez la configuration avec docker info, act --version et gitlab-ci-local --version : si docker info échoue, démarrez le moteur avant toute autre chose.

Exécutez GitHub Actions localement avec act

Exécutez act à partir du dossier racine du référentiel. Répertoriez d'abord les tâches, puis exécutez celle sur laquelle vous travaillez. Par défaut, act simule un événement push, donc les tâches qui s'exécutent uniquement sur d'autres événements ont besoin du nom de l'événement.

# list workflows and jobs
act -l

# run one job from one workflow file
act -W .github/workflows/ci.yml -j test

# simulate a pull request instead of a push
act pull_request -j test

# pass a secret the job needs
act -j deploy -s NPM_TOKEN="$NPM_TOKEN"

# Apple silicon: run x86_64 images
act -j test --container-architecture linux/amd64

La première exécution demande quelle image de coureur utiliser. Moyen convient à la plupart des projets ; les petites images manquent des outils inclus dans les coureurs hébergés, et l'image complète est très grande. Si une étape échoue avec « commande introuvable », choisissez une image plus grande avec -P ubuntu-latest=<image> ou installez l'outil dans une étape.

Exécutez GitLab CI localement avec gitlab-ci-local

gitlab-ci-local lit .gitlab-ci.yml à partir du dossier actuel. Sans aucun argument, il parcourt tout le pipeline ; donnez-lui un nom de travail pour exécuter un travail. --list affiche les tâches sans les exécuter, un moyen rapide de vérifier que YAML les analyse.

# list jobs and stages
gitlab-ci-local --list

# run one job
gitlab-ci-local test

# pass a CI/CD variable
gitlab-ci-local test --variable API_URL=http://localhost:8080

Un exemple de flux de travail à partir duquel commencer

C'est la forme de l'exemple GitHub Actions de GitTree : deux tâches, construire puis tester, qui fonctionnent de la même manière avec act et sur GitHub. Remplacez les commandes par les vôtres.

name: GitTree local check

on:
  push:
  pull_request:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - name: Test
        run: npm test

En quoi une exécution locale diffère d'un CI hébergé

• Les secrets et variables configurés sur GitHub ou GitLab ne sont pas disponibles ; passer ceux dont un travail a besoin.
• Conteneurs, pas de machines virtuelles : les services qui nécessitent systemd, ou une machine virtuelle complète, ne s'exécutent pas de la même manière.
• Les images diffèrent des coureurs hébergés ; un outil manquant est un package manquant, pas un flux de travail interrompu.
• Les événements sont simulés : act est par défaut push ; les flux de travail, inclusions et modèles réutilisables sont résolus par le coureur, et non par votre éditeur.
• Une exécution locale qui passe n'est pas un résultat hébergé : elle raccourcit la boucle ; votre hôte a toujours le dernier mot.

Erreurs et correctifs courants

Avant de pousser : prévoyez les conflits, vérifiez les secrets, prévisualisez le push

Une exécution de pipeline local répond à une question : les travaux seront-ils réussis ? Trois autres contrôles détectent ce que CI rapporte en retard ou pas du tout, et chacun d'eux s'exécute également sur votre ordinateur avant que quoi que ce soit ne soit envoyé.

1. Prédisez la fusion. git merge-tree --write-tree --name-only HEAD origin/main fusionne en mémoire et répertorie les fichiers qui seraient en conflit, sans toucher à votre arborescence de travail. GitTree effectue le même type de vérification et avertit avant une fusion qui serait en conflit ; voir comment résoudre les conflits de fusion Git.
2. Vérifiez les secrets. Avant une validation ou un push, GitTree analyse localement la modification à la recherche de jetons, de mots de passe et de clés privées probables et s'arrête avec une boîte de dialogue s'il en trouve un. Un secret qui atteint le dépôt distant doit être tourné, donc le moment le moins cher pour en attraper un est avant la poussée. Un avertissement n’est pas une garantie, alors vérifiez toujours ce que vous envoyez.
3. Prévisualisez le push. Ship Preview répertorie les commits et les fichiers que le push enverrait et, pour chaque fichier de workflow qu'il peut lire, si un pipeline S'exécutera, Peut s'exécuter ou Ne s'exécutera pas sur ce push, avec la raison.

Ensuite, exécutez le travail localement et appuyez une fois. Le guide des avertissements secrets et le guide d'aperçu du navire couvrent les deux boîtes de dialogue en détail.

Qu'en est-il de Bitbucket Pipelines et Azure Pipelines ?

Il n'existe aucun exécuteur local maintenu pour bitbucket-pipelines.yml ou azure-pipelines.yml qui correspond à act ou gitlab-ci-local. Une approche pratique consiste à conserver vos commandes de build et de test dans des scripts, à les appeler à partir de votre pipeline hébergé et à ajouter un petit fichier GitHub Actions ou GitLab CI uniquement pour les exécutions locales. GitTree marque ces fichiers Aucun coureur local et propose les exemples pour exactement cela.

Étapes suivantes : le Guide d'exécution des pipelines localement documente chaque bouton, Exécutions CI/CD couvre les exécutions hébergées, les réexécutions et les approbations, et le Lanceur d'outils répertorie les autres outils intégrés de GitTree.