Pousser un commit juste pour tester un changement de .gitlab-ci.yml, c’est 30 secondes par tentative. Sur une pipeline un peu tordue, 20 essais. 10 minutes perdues à corriger des erreurs de syntaxe.

gitlab-ci-local exécute tes pipelines en local, avec Docker. Tu modifies ton .gitlab-ci.yml, tu lances gitlab-ci-local, tu vois les erreurs immédiatement. Zéro push, zéro attente de runner.

# Installer
npm install -g gitlab-ci-local

# Lancer tous les jobs du .gitlab-ci.yml courant
gitlab-ci-local

# Lancer un job spécifique
gitlab-ci-local --job build

# Lister les jobs disponibles
gitlab-ci-local --list

Ce que ça supporte

  • image, services, before_script, script, after_script
  • artifacts, cache (local, pas partagé)
  • variables, extends, !reference, needs
  • parallel:matrix (partiellement)

Ce que ça NE supporte PAS

  • trigger (pipelines enfants)
  • environment (pas de déploiement réel)
  • rules:if avec des variables GitLab prédéfinies ($CI_COMMIT_BRANCH)
  • Runner tags, Kubernetes executor

Le piège

gitlab-ci-local utilise Docker pour exécuter les jobs. Si ton job fait référence à $CI_REGISTRY_IMAGE ou $CI_JOB_TOKEN, ces variables n’existent pas en local. Il faut les définir manuellement :

gitlab-ci-local --variable CI_REGISTRY_IMAGE=registry.gitlab.com/monprojet

Ou dans un fichier .gitlab-ci-local-variables.yml :

CI_REGISTRY_IMAGE: registry.gitlab.com/monprojet
CI_COMMIT_BRANCH: main

Autre inconvénient à prendre en compte sur des pipeline assez complexe, ton laptop pro en fin de vie ne peut pas toujours rivaliser avec le parc de runners gonflés à bloc.

C’est pas un clone parfait de GitLab, mais ça attrape 90% des erreurs avant qu’elles arrivent sur un runner distant.