🦊 GitLab CI : comprendre le pipeline .gitlab-ci.yml, pour de bon

📚 Introduction

La force de GitLab CI tient en une idée : tout le pipeline se décrit dans un seul fichier, .gitlab-ci.yml, versionné à la racine du dépôt. Pas de configuration éparpillée dans une interface web, pas d’outil externe à brancher : GitLab détecte ce fichier à chaque push et exécute ce qu’il contient. La CI/CD vit avec le code, dans le même commit.

Si vous avez déjà touché à une plateforme d’intégration continue, GitHub Actions par exemple, les concepts vous parleront, même si le vocabulaire diffère. Cet article pose les fondamentaux de GitLab CI : le modèle stages/jobs/runners, un premier pipeline complet, la distinction cache/artifacts qui pose souvent problème, et le contrôle du déclenchement avec rules. Les exemples sont volontairement agnostiques : ce qui compte, c’est la mécanique.

🧱 Le modèle : stages, jobs, runners

Trois notions structurent tout GitLab CI :

• Un job est l’unité de travail : un nom, une liste de commandes (script), et l’environnement dans lequel elles tournent.
• Un stage regroupe des jobs. Les stages s’exécutent en séquence (l’un après l’autre), mais tous les jobs d’un même stage tournent en parallèle. C’est le levier principal de rapidité : on parallélise ce qui peut l’être.
• Un runner est l’agent qui exécute réellement les jobs. GitLab.com fournit des runners partagés prêts à l’emploi ; on peut aussi héberger les siens. Chaque runner utilise un executor : le plus courant est Docker, qui lance chaque job dans un conteneur frais à partir de l’image déclarée.

L’ordre mental est donc : le pipeline enchaîne des stages, chaque stage lance ses jobs en parallèle, et chaque job s’exécute dans un conteneur sur un runner. Si aucun stage n’est déclaré, GitLab en propose trois par défaut : build, test, deploy. Et un job sans stage explicite atterrit automatiquement dans test.

Au-delà des stages que vous déclarez, GitLab fournit deux stages implicites toujours disponibles, sans avoir à les lister : .pre et .post. .pre s’exécute avant tous les autres stages, .post après tous les autres, et ce quelle que soit leur position dans le fichier. .pre est le stage de setup idéal : préparation d’environnement, vérification de prérequis, génération de variables à propager au reste du pipeline. .post sert plutôt au nettoyage ou à des notifications de fin :

verifier-prerequis:
  stage: .pre
  script:
    - ./scripts/check-env.sh
 
notifier:
  stage: .post
  when: always
  script:
    - ./scripts/notify.sh

🚀 Un premier .gitlab-ci.yml

Voici un pipeline complet et lisible. Il construit une application, la teste, puis la déploie, chaque job dans un conteneur Node :

stages:
  - build
  - test
  - deploy
 
default:
  image: node:22-alpine
 
build:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
 
test:
  stage: test
  script:
    - npm test
 
deploy:
  stage: deploy
  script:
    - ./scripts/deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Tout y est : le bloc default fixe l’image de tous les jobs (image: peut aussi être défini par job), chaque job déclare son stage et son script, le job build publie son résultat en artifacts, et deploy ne se déclenche que sur la branche par défaut grâce à rules. La variable $CI_DEFAULT_BRANCH fait partie des nombreuses variables prédéfinies fournies par GitLab (comme $CI_COMMIT_SHA ou $CI_REGISTRY_IMAGE).

🧰 Structurer un job : before_script, after_script, tags

Au-delà de script, deux mots-clés aident à factoriser les commandes répétées. before_script s’exécute avant le script du job (préparation : login, dépendances système…), after_script après, et même si le job échoue (nettoyage, remontée de logs). Placés dans le bloc default, ils s’appliquent à tous les jobs :

default:
  image: node:22-alpine
  before_script:
    - node --version
    - npm ci

Le mot-clé tags, lui, choisit quel runner exécute le job. Chaque runner déclare des étiquettes, et un job ne part que sur un runner qui possède toutes celles qu’il réclame. Indispensable pour cibler un runner self-hosted, une architecture précise ou un environnement isolé :

build-arm:
  tags:
    - arm64
    - docker
  script:
    - ./build.sh

🔎 Cache ou artifacts : quelle différence ?

C’est la confusion la plus fréquente, et les deux ne servent pas du tout à la même chose.

Le cache sert à accélérer : il conserve des fichiers coûteux à reconstituer, typiquement les dépendances téléchargées, d’un pipeline à l’autre. C’est un mécanisme best-effort : le cache peut être absent (nouveau runner, expiration), et le job doit rester correct sans lui.

test:
  stage: test
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/
  script:
    - npm ci --cache .npm --prefer-offline
    - npm test

Les artifacts, eux, servent à transmettre : un job produit des fichiers (résultat de build, rapports de test) que GitLab stocke, rend téléchargeables, et fournit aux jobs suivants qui en dépendent. Contrairement au cache, c’est fiable et prévu pour circuler entre jobs et entre stages.

La règle mnémotechnique : cache pour les dépendances, artifacts pour les résultats. Un node_modules reconstructible va au cache ; un dist/ qu’on veut déployer va aux artifacts.

🎯 Contrôler quand un job s’exécute : rules

Rares sont les jobs qui doivent tourner à chaque fois, sur toutes les branches. rules est l’outil moderne pour décider : il remplace l’ancienne syntaxe only/except, encore fonctionnelle mais à éviter pour un nouveau pipeline.

rules évalue une liste de conditions, dans l’ordre, et s’arrête à la première qui correspond :

deploy:
  stage: deploy
  script:
    - ./scripts/deploy.sh
  rules:
    # déploie automatiquement sur la branche par défaut
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    # sur les autres branches, propose un déclenchement manuel
    - if: '$CI_COMMIT_BRANCH'
      when: manual

On combine des conditions if (sur les variables prédéfinies), des filtres changes (le job ne tourne que si certains fichiers ont changé), des vérifications exists, et des clauses when (on_success, manual, never…). C’est expressif et centralisé, là où only/except devenait vite illisible.

🧩 Aller plus loin : needs, variables, include

Trois mots-clés font passer un pipeline du niveau « ça marche » à « c’est propre » :

• needs casse la barrière des stages pour créer un graphe de dépendances (DAG). Un job avec needs: ['build'] démarre dès que build est fini, sans attendre la fin de tout le stage. Les pipelines deviennent nettement plus rapides.
• variables définit des valeurs réutilisables, globalement ou par job, pour ne pas répéter une version, un chemin ou un nom d’image.
• include importe de la configuration depuis l’extérieur, pour factoriser des pipelines entre projets. Il en existe plusieurs formes : include:local (un autre fichier du même dépôt), include:project (un fichier d’un autre projet GitLab), include:remote (une URL), include:template (un modèle fourni par GitLab) et include:component (un CI/CD component du catalogue).

include:
  - local: '/ci/tests.yml'
  - project: 'mon-groupe/ci-templates'
    ref: main
    file: '/deploy.yml'
  - component: '$CI_SERVER_FQDN/mon-groupe/build@1.0'

Les CI/CD components sont la brique moderne : des morceaux de pipeline réutilisables, versionnés et paramétrables, publiés dans un catalogue et importés via include:component. C’est la direction que pousse GitLab pour mutualiser la CI proprement.

Ces trois leviers évitent la duplication, le péché mignon des fichiers CI qui grossissent.

⚠️ Quelques précautions

• Validez avant de pousser. GitLab fournit un outil CI Lint (dans le menu CI/CD du projet) qui vérifie la syntaxe du .gitlab-ci.yml sans lancer de pipeline. Un aller-retour de moins pour débusquer une indentation fautive.
• Ne stockez jamais de secret en clair dans .gitlab-ci.yml. Utilisez les variables CI/CD masquées et protégées définies dans les réglages du projet, jamais une valeur codée en dur dans un fichier versionné.
• Un cache n’est pas garanti. Écrivez vos jobs pour qu’ils fonctionnent même cache vide. Si un fichier est indispensable au job suivant, c’est un artifact, pas un cache.
• Épinglez vos images. node:22-alpine reste prévisible ; node:latest change sous vos pieds et rend les pipelines non reproductibles.
• Surveillez la durée des artifacts. Ils consomment du stockage. Fixez une expire_in raisonnable pour ceux qui n’ont pas vocation à durer.

🎉 Conclusion

GitLab CI tient sur une poignée de concepts : des jobs regroupés en stages séquentiels, exécutés en parallèle par des runners dans des conteneurs. Autour de ce cœur, quatre outils suffisent à couvrir l’essentiel : artifacts pour transmettre les résultats, cache pour accélérer, rules pour décider quand un job tourne, et needs/include pour garder le tout rapide et sans duplication.

L’atout majeur reste la simplicité du modèle : un fichier, versionné avec le code, qui décrit tout le pipeline. Une fois le mental model en place, écrire un .gitlab-ci.yml devient une formalité. Et comme chaque job tourne dans une image Docker, une bonne maîtrise des fondamentaux de Docker rend l’exercice encore plus naturel.

🔗 Liens utiles

• GitLab CI/CD — documentation officielle
• Référence des mots-clés .gitlab-ci.yml
• GitLab Runner — documentation
• Variables prédéfinies de GitLab CI/CD
• Fondamentaux GitLab CI/CD — blog de Stéphane Robert (ressource FR pour aller plus loin)