Un pipeline qui passe au vert n'est pas la même chose qu'un pipeline fiable. Beaucoup d'équipes ont un .gitlab-ci.yml qui "marche" mais qui prend douze minutes pour un changement d'une ligne, qui redéploie en production sur un simple push, ou qui cache des échecs de tests derrière un job mal configuré. Voici comment construire un pipeline GitLab CI qui tient la route en conditions réelles, pas seulement sur la branche de démo.
Le problème concret
Imaginons une application Node.js/NestJS avec une base PostgreSQL, déployée sur plusieurs environnements (staging, production). Le besoin : à chaque merge request, lancer lint, tests unitaires et tests d'intégration contre une vraie base ; au merge sur main, builder une image Docker versionnée et la déployer en staging automatiquement, puis en production sur validation manuelle.
L'erreur fréquente est de tout mettre dans un seul job séquentiel, sans cache, sans séparation claire entre "build", "test" et "deploy", et sans distinguer ce qui doit être automatique de ce qui doit rester un geste humain explicite.
Pourquoi un pipeline mal conçu dégrade vite
Trois mécanismes expliquent la plupart des pipelines lents ou dangereux :
- Pas de cache ou cache mal scopé : réinstaller
node_modulesou les dépendances Composer à chaque job multiplie le temps de pipeline par le nombre de jobs, alors que GitLab CI offre un cache natif par clé. - Jobs non parallélisés : lint, tests unitaires et tests d'intégration n'ont aucune dépendance entre eux mais sont souvent enchaînés dans un seul
stage, ce qui sérialise inutilement le temps d'attente du développeur. - Déploiement non différencié par branche/environnement : sans règles
rules:explicites, un pipeline peut déployer en production depuis n'importe quelle branche, ce qui est le scénario catastrophe classique d'un push accidentel.
Diagnostiquer un pipeline existant
Avant de réécrire quoi que ce soit, GitLab donne des outils de diagnostic qu'on sous-utilise :
# Durée détaillée de chaque job du dernier pipeline sur main
glab ci view --branch main
# Repérer les jobs qui dépassent 5 minutes sur les 20 derniers pipelines
glab api "projects/:id/pipelines?ref=main&per_page=20" \
| jq -r '.[].id' \
| xargs -I{} glab api "projects/:id/pipelines/{}/jobs" \
| jq '.[] | select(.duration > 300) | {name, duration}'
Ça permet de cibler le vrai goulot d'étranglement (souvent l'installation de dépendances ou un test d'intégration qui attend un service pas encore prêt) plutôt que d'optimiser au hasard.
Un pipeline structuré
Stages et cache
stages:
- build
- test
- deploy
variables:
npm_config_cache: "$CI_PROJECT_DIR/.npm-cache"
default:
image: node:20-alpine
cache:
key:
files:
- package-lock.json
paths:
- .npm-cache/
- node_modules/
install:
stage: build
script:
- npm ci --prefer-offline
artifacts:
paths:
- node_modules/
expire_in: 1 hour
La clé de cache basée sur package-lock.json évite deux pièges courants : un cache jamais invalidé (dépendances obsolètes utilisées silencieusement) et un cache invalidé à chaque run (aucun gain). npm ci plutôt que npm install garantit une installation reproductible à partir du lockfile, point important en CI où la reproductibilité prime sur la commodité.
Parallélisation des vérifications
lint:
stage: test
needs: ["install"]
script:
- npm run lint
unit-tests:
stage: test
needs: ["install"]
script:
- npm run test:unit -- --coverage
coverage: '/All files[^|]*\|[^|]*\s+([\d.]+)/'
integration-tests:
stage: test
needs: ["install"]
services:
- postgres:16-alpine
variables:
POSTGRES_DB: test_db
POSTGRES_USER: test
POSTGRES_PASSWORD: test
DATABASE_URL: "postgresql://test:test@postgres:5432/test_db"
script:
- npm run migrate
- npm run test:integration
Le mot-clé needs (plutôt que la dépendance implicite entre stage) permet à ces trois jobs de démarrer dès que install est terminé, en parallèle, au lieu d'attendre la fin séquentielle du stage précédent. Le service postgres tourne comme conteneur sidecar accessible par son nom de service (postgres) depuis le job, ce qui évite de mocker la base pour des tests d'intégration qui perdent alors toute valeur.
Build d'image Docker versionnée
build-image:
stage: build
image: docker:24-cli
services:
- docker:24-dind
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
script:
- docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
- docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
Taguer l'image avec $CI_COMMIT_SHORT_SHA plutôt que latest est ce qui rend un rollback possible : sans tag traçable, revenir à la version précédente en production veut dire reconstruire à partir du commit précédent, pas simplement redéployer une image déjà testée.
Déploiement contrôlé par environnement
deploy-staging:
stage: deploy
environment:
name: staging
url: https://staging.example.com
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
script:
- kubectl set image deployment/app app="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" -n staging
deploy-production:
stage: deploy
environment:
name: production
url: https://example.com
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
when: manual
script:
- kubectl set image deployment/app app="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" -n production
Le when: manual sur deploy-production est la vraie barrière de sécurité, pas une convention informelle ("on évite de push sur main le vendredi"). Le mot-clé environment: donne en plus l'historique de déploiement par environnement dans l'UI GitLab, utile pour tracer quelle version tourne où sans avoir à aller chercher dans les logs.
Les compromis
- Cache GitLab natif vs registre de dépendances partagé (Verdaccio, Artifactory) : le cache par job est simple mais reparti de zéro par runner si l'infrastructure change ; un registre partagé est plus robuste mais ajoute un composant à maintenir. Pour une seule équipe sur un seul projet, le cache natif suffit largement.
dind(Docker-in-Docker) vs kaniko :dindest plus simple à configurer mais tourne en mode privilégié, ce qui est une surface d'attaque réelle sur un runner partagé.kanikobuild les images sans privilèges mais a une syntaxe et des contraintes différentes qu'il faut apprendre.- Déploiement manuel vs automatique en production : l'automatisation totale réduit la friction mais retire le dernier filet de sécurité humain. Un
when: manualcombiné à des tests d'intégration solides est souvent le bon compromis plutôt que de choisir un extrême.
Quand ce pipeline ne suffit plus
Ce schéma couvre bien une application monolithique ou un petit nombre de services. Il devient insuffisant pour un monorepo avec plusieurs services indépendants : il faut alors des règles rules:changes: pour ne builder/tester que ce qui a changé, et probablement un outil de build incrémental (Nx, Turborepo) en complément de GitLab CI, sous peine de pipelines qui durent des dizaines de minutes même pour un changement isolé.
Garder le pipeline rapide dans la durée
Un pipeline rapide le jour de sa mise en place se dégrade mécaniquement avec le temps : chaque nouvelle feature ajoute un test, chaque nouveau test ajoute quelques secondes, et personne ne remarque la dérive tant qu'elle reste progressive. Deux pratiques évitent ce piège sans discipline héroïque :
- Un budget de durée explicite par stage, vérifié automatiquement plutôt que surveillé à l'œil. GitLab permet de faire échouer un job si un seuil est dépassé, ce qui transforme une dérive silencieuse en alerte visible dans la merge request concernée, au moment où elle est introduite.
- Des runners dimensionnés pour le profil réel de charge, pas pour la moyenne. Une suite de tests d'intégration qui monte une base PostgreSQL complète a besoin de plus de RAM qu'un job de lint ; mutualiser un seul type de runner pour tous les jobs gaspille soit du temps (runner sous-dimensionné pour les tests lourds), soit du budget (runner surdimensionné pour le lint).
integration-tests:
stage: test
needs: ["install"]
tags:
- docker-runner-highmem # runner dédié, dimensionné pour postgres + migrations
services:
- postgres:16-alpine
script:
- npm run migrate
- npm run test:integration
timeout: 8m # échoue explicitement plutôt que de dériver silencieusement
À retenir
Un pipeline fiable repose sur trois décisions : un cache correctement scopé pour ne pas payer le prix de l'installation à chaque job, une parallélisation explicite via needs pour ne pas sérialiser ce qui est indépendant, et des règles de déploiement qui rendent la production inaccessible par accident. Le reste n'est que de la syntaxe YAML.
