Exécuter un pipeline GitLab en local avec gitlab-ci-local

Si vous développez sous GitLab CI/CD, vous avez probablement déjà dû attendre plusieurs minutes pour tester une simple modification de .gitlab-ci.yml. Heureusement, un outil open source existe pour simuler vos pipelines en local : gitlab-ci-local.

Dans cet article, nous vous proposons un guide pour démarrer efficacement avec gitlab-ci-local, en l’intégrant à votre flux de travail DevOps.

Sommaire optimisé SEO

  • Qu’est-ce que gitlab-ci-local ?
  • Pourquoi utiliser gitlab-ci-local ?
  • Prérequis et installation
  • Configuration des variables d’environnement
  • Exécution locale d’un job GitLab CI
  • Fichiers de configuration disponibles
  • Limitations connues
  • Bonnes pratiques

Qu’est-ce que gitlab-ci-local ?

gitlab-ci-local est un outil CLI permettant d’exécuter localement des jobs définis dans un fichier .gitlab-ci.yml sans avoir besoin de pousser du code sur un dépôt GitLab. Il simule fidèlement l’environnement d’exécution GitLab Runner en utilisant Docker.

Pourquoi utiliser gitlab-ci-local ?

Voici quelques cas d’usage typiques :

  • Valider rapidement un .gitlab-ci.yml avant un commit
  • Déboguer un job complexe sans polluer l’historique Git
  • Travailler hors ligne sans accès à GitLab
  • Simuler des variables d’environnement ou des tags

Prérequis et installation

  • Docker doit être installé et fonctionnel
  • Node.js (recommandé pour installer en global)
npm install -g gitlab-ci-local

Vérification :

gitlab-ci-local --version

Configuration des variables d’environnement

Contrairement aux runners GitLab, vous devez expliciter vos variables.

Fichier .gitlab-ci-local-variables.yml

Placez ce fichier à la racine de votre projet :

# .gitlab-ci-local-variables.yml
CI_COMMIT_TAG: "2025.2.12"
CI_COMMIT_SHORT_SHA: "ea8b46a2"
NEXUS_CREDENTIALS_USR: "deployer"
NEXUS_CREDENTIALS_PSW: "SuperSecret"
NEXUS_ADDRESS: "https://nexus.example.com/repository"

Exécution locale d’un job GitLab CI

Lancez simplement l’outil à la racine du dépôt :

gitlab-ci-local

Utilisez les flèches pour choisir le job à exécuter.

Exemple pour forcer un job à être considéré comme « tagué » :

# .gitlab-ci-local-variables.yml
CI_COMMIT_TAG: "2025.2.12"

Fichiers spécifiques

FichierRôle
.gitlab-ci-local-variables.ymlVariables d’environnement locales
$HOME/.gitlab-ci-local/variables.ymlVariables globales par projet ou groupe
.gitlab-ci-local-envFichier de config de l’outil (alias, proxy, debug…)

Limitations connues

  • Pas de support des includes dynamiques depuis un repo GitLab distant
  • Pas d’interaction avec les environments Kubernetes
  • Certains scripts très dépendants de GitLab API peuvent échouer

Bonnes pratiques

  • Gardez un .gitlab-ci-local-variables.yml à jour pour vos tests locaux
  • Utilisez --debug pour tracer l’exécution
  • Ajoutez une vérification dans vos PRs : « Testé localement avec gitlab-ci-local »

Conclusion

gitlab-ci-local est un outil incontournable pour les développeurs et DevOps qui souhaitent accélérer leur boucle de feedback CI/CD. Facile à intégrer, il permet de gagner du temps, réduire les erreurs et fiabiliser vos pipelines GitLab.

Pensez à l’ajouter à votre documentation projet ou README pour faciliter l’onboarding de nouveaux collaborateurs.

Mots-clés SEO

gitlab-ci-local, exécuter pipeline GitLab en local, CI/CD GitLab offline, tester gitlab-ci.yml localement, simulateur GitLab CI, debug GitLab CI

Étiquettes

Publications similaires