GitLab CI/CD est une plateforme d’intégration et de livraison continues intégrée directement dans GitLab. Contrairement aux outils CI externes qui nécessitent une configuration séparée et des webhooks, GitLab CI/CD lit un unique fichier .gitlab-ci.yml depuis votre dépôt et exécute les pipelines automatiquement à chaque push. Cette intégration étroite signifie que votre code, vos issues, vos merge requests et vos pipelines de déploiement cohabitent au même endroit.

Ce guide couvre la configuration des pipelines de A à Z — stages, jobs, runners, cache, artefacts, variables, environnements et stratégies de déploiement prêts pour la production.

Prérequis

  • Un compte GitLab (gitlab.com ou instance auto-hébergée)
  • Un dépôt Git hébergé sur GitLab
  • Connaissance de base de la syntaxe YAML
  • Docker installé (pour les runners avec executor Docker)
  • Familiarité avec les concepts CI/CD (build, test, deploy)

Comprendre la Structure d’un Pipeline GitLab CI/CD

Un pipeline se compose de stages qui s’exécutent séquentiellement et de jobs au sein de chaque stage qui s’exécutent en parallèle. Voici la structure fondamentale :

# .gitlab-ci.yml
stages:
  - build
  - test
  - deploy

build-app:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

unit-tests:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm run test:unit
  coverage: '/Lines\s+:\s+(\d+\.?\d*)%/'

integration-tests:
  stage: test
  image: node:20
  services:
    - postgres:15
  variables:
    POSTGRES_DB: test_db
    POSTGRES_USER: runner
    POSTGRES_PASSWORD: testing
    DATABASE_URL: "postgresql://runner:testing@postgres:5432/test_db"
  script:
    - npm ci
    - npm run test:integration

deploy-staging:
  stage: deploy
  script:
    - ./scripts/deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"

Le stage build s’exécute en premier. Lorsqu’il réussit, les deux jobs de test s’exécutent en parallèle (ils appartiennent au même stage). Le déploiement ne commence que si tous les tests passent.

Configurer les GitLab Runners

Les runners exécutent les jobs de votre pipeline. Deux options s’offrent à vous :

Runners Partagés (Démarrage Rapide)

GitLab.com fournit des runners partagés gratuitement. Ils sont disponibles immédiatement — aucune configuration requise. Rendez-vous dans Settings → CI/CD → Runners pour vérifier qu’ils sont activés.

Runners Auto-Hébergés (Production)

Pour de meilleures performances et un meilleur contrôle, installez votre propre runner :

# Installer GitLab Runner sur Ubuntu
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt-get install gitlab-runner

# Enregistrer le runner
sudo gitlab-runner register \
  --url "https://gitlab.com/" \
  --registration-token "YOUR_TOKEN" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "production-runner" \
  --tag-list "docker,linux" \
  --run-untagged="true"

Comparaison des Executors de Runner

ExecutorIsolationVitesseCas d’usage
DockerÉlevée (conteneur par job)RapideChoix par défaut pour la plupart des projets
ShellAucune (s’exécute sur l’hôte)Très rapideScripts simples, applications legacy
Docker MachineÉlevée + autoscalingVariableRunners autoscaling dans le cloud
KubernetesÉlevée (pod par job)MoyenneDéploiements natifs Kubernetes
VirtualBoxVM complèteLenteIsolation complète du système d’exploitation requise

Configuration Avancée des Pipelines

Cache des Dépendances

Le cache évite de retélécharger les dépendances à chaque exécution du pipeline :

variables:
  NPM_CONFIG_CACHE: "$CI_PROJECT_DIR/.npm"

cache:
  key:
    files:
      - package-lock.json
  paths:
    - .npm/
    - node_modules/
  policy: pull-push

La directive key.files génère une clé de cache à partir de package-lock.json. Lorsque les dépendances changent, le cache est automatiquement invalidé.

Artefacts entre les Stages

Transmettez les résultats de build d’un stage au suivant :

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
      - coverage/
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
    expire_in: 1 week

Règles et Exécution Conditionnelle

Contrôlez quand les jobs s’exécutent avec rules :

deploy-production:
  stage: deploy
  script:
    - ./deploy.sh production
  environment:
    name: production
    url: https://example.com
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
      when: manual
    - when: never

Ce job n’apparaît que sur les tags de version (v1.2.3) et nécessite une approbation manuelle.

Jobs Matrix en Parallèle

Testez sur plusieurs versions simultanément :

test:
  stage: test
  image: node:${NODE_VERSION}
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
        DATABASE: ["postgres", "mysql"]
  script:
    - npm ci
    - npm run test

Cela crée 6 jobs parallèles (3 versions de Node × 2 bases de données).

Variables CI/CD et Secrets

Stockez les valeurs sensibles en toute sécurité :

deploy:
  stage: deploy
  script:
    - echo "$DEPLOY_KEY" > key.pem
    - chmod 600 key.pem
    - scp -i key.pem dist/* user@server:/var/www/
  after_script:
    - rm -f key.pem

Scénario réel : Votre équipe déploie une application Node.js dans trois environnements — développement, staging et production. Chaque environnement possède des identifiants de base de données, des clés API et des adresses de serveur différents. Vous les stockez en tant que variables GitLab CI/CD limitées à leurs environnements respectifs. Le même fichier YAML gère tous les déploiements ; seules les variables diffèrent. Lorsqu’un développeur pousse sur develop, le pipeline se déploie automatiquement en staging. Le déploiement en production ne se déclenche que sur les tags avec approbation manuelle d’un lead technique.

Types de Variables et Portées

PortéeDéfinie dansDisponible pour
ProjetSettings → CI/CD → VariablesTous les pipelines du projet
GroupeGroup → Settings → CI/CDTous les projets du groupe
InstanceAdmin → CI/CD → VariablesTous les projets de l’instance
EnvironnementSettings → CI/CD → Variables (filtre env)Les jobs ciblant cet environnement
Jobvariables: dans .gitlab-ci.ymlCe job spécifique uniquement

Marquez les variables comme Protected (disponibles uniquement sur les branches/tags protégés) et Masked (masquées dans les logs des jobs) pour les identifiants.

Environnements de Déploiement et Stratégies

Review Apps (Environnements Dynamiques)

Créez un environnement temporaire pour chaque merge request :

review:
  stage: deploy
  script:
    - deploy_review_app "$CI_MERGE_REQUEST_IID"
  environment:
    name: review/$CI_MERGE_REQUEST_IID
    url: https://$CI_MERGE_REQUEST_IID.review.example.com
    on_stop: stop-review
  rules:
    - if: $CI_MERGE_REQUEST_IID

stop-review:
  stage: deploy
  script:
    - teardown_review_app "$CI_MERGE_REQUEST_IID"
  environment:
    name: review/$CI_MERGE_REQUEST_IID
    action: stop
  rules:
    - if: $CI_MERGE_REQUEST_IID
      when: manual

Déploiement en Production avec Rollback

deploy-production:
  stage: deploy
  script:
    - ./deploy.sh production
  environment:
    name: production
    url: https://example.com
    auto_stop_in: never
  rules:
    - if: $CI_COMMIT_TAG
      when: manual
  allow_failure: false

GitLab CI/CD vs Autres Plateformes CI

FonctionnalitéGitLab CI/CDGitHub ActionsJenkinsCircleCI
Fichier de config.gitlab-ci.yml.github/workflows/*.ymlJenkinsfile.circleci/config.yml
Registre intégréOui (conteneurs + paquets)Oui (conteneurs)NonNon
Option auto-hébergéeOui (GitLab complet)Oui (runners uniquement)OuiNon
Review AppsNatifConfiguration manuelleManuelleManuelle
Pipelines DAGOui (mot-clé needs)Oui (natif)OuiOui
Auto DevOpsOuiNonNonNon
Minutes CI gratuites400 min/mois2 000 min/moisIllimité (auto-hébergé)6 000 min/mois
Courbe d’apprentissageMoyenneFaibleÉlevéeFaible

GitLab CI/CD excelle lorsque vous souhaitez tout centraliser — code, CI, registre de conteneurs, environnements et monitoring dans une seule plateforme. GitHub Actions l’emporte sur l’étendue de l’écosystème grâce à son marketplace.

Pièges et Cas Particuliers

  • Les ancres YAML ne fonctionnent pas avec include : Si vous utilisez des ancres YAML (&anchor/*anchor) dans des fichiers inclus, elles ne seront pas résolues entre fichiers. Utilisez plutôt le mot-clé extends.

  • Le cache n’est pas garanti : Les caches GitLab sont en mode best-effort. Les runners ne partagent pas forcément les caches. Concevez toujours des pipelines qui fonctionnent sans cache (juste plus lentement).

  • Réseau des services : Les conteneurs de services (comme postgres:15) sont accessibles via le nom de leur image en tant que hostname. postgres, pas localhost. Cela déroute beaucoup de développeurs.

  • only/except vs rules : La syntaxe legacy only/except est incompatible avec rules. Ne les mélangez jamais dans le même job. Préférez rules — c’est plus puissant et l’approche recommandée.

  • Le timeout des jobs est de 1 heure par défaut : Les jobs de longue durée comme les tests E2E ou les gros builds échouent silencieusement au timeout. Définissez explicitement timeout: 2h pour les jobs connus pour être longs.

  • Variables de branches protégées : Les variables marquées “Protected” ne sont pas disponibles sur les branches de fonctionnalité. Si un job a besoin d’identifiants sur des branches non protégées, utilisez une variable distincte sans l’indicateur protected.

Résolution de Problèmes

ProblèmeCauseSolution
Pipeline bloqué sur “Pending”Aucun runner disponible avec les tags correspondantsVérifiez les tags du runner ou définissez tags: [] pour utiliser n’importe quel runner
”Cache not found” à la première exécutionLe cache n’a pas encore été crééLa première exécution télécharge tout ; le cache se remplit pour la prochaine exécution
Services inaccessiblesMauvais hostname dans la chaîne de connexionUtilisez le nom de l’image du service comme hostname (ex. postgres, pas localhost)
“Variable is not set” dans les jobsLa variable est protégée, la branche ne l’est pasDécochez “Protected” ou poussez sur une branche protégée
Artefacts manquants dans le stage suivantartifacts.paths ne correspond pas à la sortieVérifiez les chemins exacts ; utilisez ls -la dans le script pour déboguer

Résumé

  • GitLab CI/CD lit .gitlab-ci.yml depuis votre dépôt et exécute les pipelines automatiquement — aucune configuration d’outil externe nécessaire
  • Les stages s’exécutent séquentiellement tandis que les jobs au sein d’un stage s’exécutent en parallèle, offrant à la fois ordonnancement et rapidité
  • Les runners auto-hébergés avec executor Docker offrent les meilleures performances et le meilleur contrôle pour les équipes en production
  • Le cache des dépendances et la transmission des artefacts entre stages réduisent considérablement le temps d’exécution des pipelines
  • Les variables d’environnement avec masquage, protection et portée par environnement assurent la sécurité des secrets à travers les déploiements
  • Les review apps créent des environnements temporaires par merge request, permettant une revue visuelle avant le merge

Articles Connexes