Écrire un fichier .gitlab-ci.yml

Vous connaissez maintenant les concepts fondamentaux : pipeline, stages, jobs, runners. Il est temps de passer à la pratique ! Le fichier .gitlab-ci.yml décrit ce que GitLab doit automatiser. Ce guide vous apprend à le structurer méthodiquement : comment découper votre workflow en stages, définir des jobs, et écrire les scripts qui seront exécutés.

En 30 secondes

Un fichier .gitlab-ci.yml se construit en 3 niveaux :

1. Stages — Les grandes étapes (build, test, deploy)
2. Jobs — Les tâches dans chaque stage
3. Script — Les commandes exécutées par chaque job

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Structurer un fichier .gitlab-ci.yml : la hiérarchie stages → jobs → script
• Définir des stages : organiser les grandes étapes de votre pipeline
• Créer des jobs : configurer les tâches avec les bonnes propriétés
• Écrire des scripts : les commandes exécutées par chaque job
• Spécifier une image Docker : choisir l’environnement d’exécution
• Utiliser les variables : configurer vos jobs dynamiquement
• Valider votre fichier : éviter les erreurs de syntaxe

Prérequis

Avant de continuer, assurez-vous de maîtriser :

• Concepts fondamentaux GitLab CI/CD

La logique de construction

Avant d’écrire du YAML, posez-vous ces questions :

1. Quelles sont les grandes étapes de mon workflow ? → Ce seront vos stages
2. Quelles tâches dois-je accomplir à chaque étape ? → Ce seront vos jobs
3. Quelles commandes chaque tâche doit-elle exécuter ? → Ce sera le script

Exemple de raisonnement pour un projet web :

Question	Réponse	Élément YAML
Grandes étapes ?	Compiler, tester, déployer	stages: [build, test, deploy]
Tâches du test ?	Tests unitaires, linting	2 jobs dans le stage test
Commandes du lint ?	npm run lint	script: [npm run lint]

Glissez pour voir

Structure minimale du fichier

Un fichier .gitlab-ci.yml valide contient au minimum :

# 1. Déclarer les stages (optionnel mais recommandé)
stages:
  - build
  - test

# 2. Définir au moins un job avec un script
mon-job:
  stage: build
  script:
    - echo "Hello GitLab CI!"

Le fichier doit être :

• Nommé exactement .gitlab-ci.yml (avec le point)
• Placé à la racine du repository
• Encodé en UTF-8

Niveau 1 : Définir les stages

Les stages représentent les grandes étapes de votre pipeline. Ils s’exécutent dans l’ordre déclaré.

stages:
  - build      # Étape 1 : compiler le code
  - test       # Étape 2 : exécuter les tests
  - deploy     # Étape 3 : déployer l'application

Règles des stages :

Règle	Explication
Ordre séquentiel	build se termine avant que test commence
Échec bloquant	Si build échoue, test et deploy ne s’exécutent pas
Stages par défaut	Sans déclaration, GitLab utilise : build, test, deploy

Glissez pour voir

Combien de stages ?

Commencez simple : 2-3 stages suffisent pour la plupart des projets. Ajoutez-en si vous avez des besoins spécifiques (analyse de sécurité, documentation, etc.).

Quand créer un nouveau stage ?

Créez un stage quand vous avez une dépendance logique :

• ✅ test dépend de build → 2 stages séparés
• ✅ deploy-staging avant deploy-prod → 2 stages séparés
• ❌ Tests unitaires et tests d’intégration → même stage (pas de dépendance)

Niveau 2 : Définir les jobs

Un job est une tâche qui appartient à un stage. C’est ici que vous décrivez ce qui doit être fait.

# Syntaxe d'un job
nom-du-job:           # Nom libre, visible dans l'interface
  stage: test         # À quel stage appartient ce job
  script:             # Commandes à exécuter (OBLIGATOIRE)
    - commande1
    - commande2

Les propriétés d’un job

Propriété	Obligatoire	Description
script	✅ Oui	Liste des commandes à exécuter
stage	Non	Stage d’appartenance (défaut: test)
image	Non	Image Docker pour l’environnement
variables	Non	Variables d’environnement du job
artifacts	Non	Fichiers à conserver après le job
cache	Non	Fichiers à réutiliser entre pipelines
rules	Non	Conditions d’exécution
needs	Non	Dépendances explicites (ignore l’ordre des stages)

Glissez pour voir

Jobs en parallèle

Les jobs d’un même stage s’exécutent en parallèle :

stages:
  - test

test-unitaires:
  stage: test
  script:
    - npm run test:unit

test-integration:
  stage: test
  script:
    - npm run test:integration

lint:
  stage: test
  script:
    - npm run lint

Ces 3 jobs démarrent simultanément car ils sont tous dans le stage test.

Niveau 3 : Écrire les scripts

Le script contient les commandes shell exécutées par le job.

build:
  stage: build
  script:
    - echo "Début du build"
    - npm ci
    - npm run build
    - echo "Build terminé"

Règles du script

Règle	Exemple
Chaque ligne = une commande	- npm install
Exécution séquentielle	Ligne 1, puis ligne 2, puis ligne 3…
Échec = arrêt	Si une commande retourne un code ≠ 0, le job échoue
Shell par défaut	/bin/sh (ou celui de l’image Docker)

Glissez pour voir

Commandes multi-lignes

Pour des commandes longues, utilisez le pipe YAML | :

script:
  - |
    echo "Première ligne"
    echo "Deuxième ligne"
    if [ -f "config.json" ]; then
      echo "Config trouvée"
    fi

before_script et after_script

Utilisez ces sections pour factoriser du code :

# S'exécute AVANT le script de chaque job
default:
  before_script:
    - echo "Préparation..."
    - npm ci

test:
  script:
    - npm test
  after_script:
    - echo "Nettoyage..."  # S'exécute même si le job échoue

Spécifier l’environnement avec image

Par défaut, les jobs s’exécutent dans une image Docker Ruby. Spécifiez une image adaptée :

build:
  image: node:18-alpine    # Node.js 18 sur Alpine Linux
  script:
    - node --version
    - npm ci
    - npm run build

Images recommandées :

Langage	Image légère	Image complète
Node.js	node:18-alpine	node:18
Python	python:3.11-slim	python:3.11
Go	golang:1.21-alpine	golang:1.21
Java	eclipse-temurin:17-alpine	eclipse-temurin:17
Générique	alpine:3.19	ubuntu:22.04

Glissez pour voir

Jamais de :latest en CI !

Si vous voulez éviter les surprises, ne jamais utiliser une image avec le tag :latest. Précisez toujours une version fixe !

Définir des variables

Les variables permettent de configurer vos jobs sans modifier le script.

Variables globales

variables:
  NODE_ENV: production
  DEPLOY_TARGET: staging

build:
  script:
    - echo "Environment: $NODE_ENV"
    - echo "Target: $DEPLOY_TARGET"

Variables par job

build:
  variables:
    NODE_ENV: development
  script:
    - npm run build

deploy:
  variables:
    NODE_ENV: production
  script:
    - npm run deploy

Variables prédéfinies GitLab

GitLab injecte automatiquement des variables utiles :

Variable	Contenu
$CI_COMMIT_BRANCH	Nom de la branche
$CI_COMMIT_SHORT_SHA	Hash court du commit
$CI_PROJECT_NAME	Nom du projet
$CI_PIPELINE_SOURCE	Déclencheur (push, merge_request, etc.)
$CI_JOB_NAME	Nom du job en cours

Glissez pour voir

build:
  script:
    - echo "Building $CI_PROJECT_NAME on branch $CI_COMMIT_BRANCH"
    - echo "Commit: $CI_COMMIT_SHORT_SHA"

Exemple complet commenté

Voici un pipeline réaliste pour un projet Node.js :

# Déclaration des stages dans l'ordre d'exécution
stages:
  - build
  - test
  - deploy

# Variables globales disponibles dans tous les jobs
variables:
  NODE_ENV: production

# --- STAGE BUILD ---
build:
  stage: build
  image: node:18-alpine
  script:
    - echo "📦 Installation des dépendances..."
    - npm ci
    - echo "🔨 Compilation..."
    - npm run build
  artifacts:
    paths:
      - dist/           # Conserve le dossier dist/ pour les jobs suivants
    expire_in: 1 hour   # Supprimé après 1 heure

# --- STAGE TEST ---
# Ces 2 jobs s'exécutent EN PARALLÈLE
test-unit:
  stage: test
  image: node:18-alpine
  script:
    - npm ci
    - npm run test:unit

test-lint:
  stage: test
  image: node:18-alpine
  script:
    - npm ci
    - npm run lint

# --- STAGE DEPLOY ---
deploy:
  stage: deploy
  image: alpine:3.19
  script:
    - echo "🚀 Déploiement vers $DEPLOY_TARGET..."
    - echo "Fichiers à déployer:" && ls dist/
  rules:
    - if: $CI_COMMIT_BRANCH == "main"   # Seulement sur main
      when: manual                       # Clic requis pour démarrer

Valider avant de commiter

Avant de pusher, validez votre fichier :

1. Dans GitLab : Build > Pipeline editor > Validate
2. En local avec l’outil gitlab-ci-lint :

   npm install -g gitlab-ci-lint
   gitlab-ci-lint .gitlab-ci.yml

Erreurs courantes

• Indentation : utilisez 2 espaces, jamais de tabulations
• Tirets : les éléments de liste commencent par - (tiret + espace)
• Guillemets : utilisez-les pour les valeurs avec caractères spéciaux

À retenir

Niveau	Élément	Rôle
1	stages	Définit l’ordre des grandes étapes
2	Jobs	Tâches à accomplir (nommées librement)
3	script	Commandes shell à exécuter

Glissez pour voir

Construction logique :

1. Listez vos étapes → stages
2. Pour chaque étape, listez les tâches → jobs
3. Pour chaque tâche, listez les commandes → script

Contrôle des connaissances

Testez vos connaissances sur la structure des fichiers .gitlab-ci.yml.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

5 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Prochaines étapes

Valider son pipeline Vérifier la syntaxe avant de pusher.

Debug : lire les logs Comprendre les erreurs dans les logs des jobs.

Runners Comprendre où et comment vos jobs s'exécutent.

×

📖 Voir la documentation →