É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

On passe à la pratique

Vous avez la méthode pour structurer un .gitlab-ci.yml. Passez maintenant sur un vrai cas guidé pour l'appliquer étape par étape dans GitLab.

Passez au Lab 01, Mon premier pipeline pour construire votre premier pipeline complet.

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 →