🧭 Introduction
Automatiser les tâches de développement est devenu un incontournable dans les projets web modernes. Que ce soit pour lancer des tests, compiler du code, effectuer des déploiements ou encore vérifier la qualité du code, l’automatisation permet de gagner du temps, d’assurer une meilleure fiabilité, et de favoriser le travail collaboratif.
Parmi les solutions d’intégration continue (CI) les plus utilisées, GitLab CI/CD se distingue par sa puissance, sa flexibilité, et surtout, son intégration native dans l’environnement GitLab. Le cœur de cette automatisation repose sur un seul fichier : .gitlab-ci.yml
.
Ce fichier permet de définir toutes les étapes d’un pipeline CI/CD : compilation, tests, build, déploiement… sans avoir besoin de configurer un outil externe. Dans cet article, nous allons poser les bases d’une compréhension claire et vulgarisée du fichier .gitlab-ci.yml
, pour que vous puissiez créer vos premiers pipelines de CI/CD même en tant que débutant.
🔍 Contexte
Qu'est-ce que la CI/CD ?
La CI/CD (Intégration Continue / Déploiement Continu) est une pratique consistant à automatiser les étapes de construction, de test et de déploiement d'une application dès qu’un changement est apporté au code source.
- CI (Continuous Integration) : détecte automatiquement les changements dans le code (ex : une nouvelle merge request) et exécute une série de jobs (tests, linting, build…).
- CD (Continuous Delivery/Deployment) : automatise le déploiement du code dans un environnement (de test, de production…).
Cela permet :
- de repérer rapidement les bugs introduits,
- de réduire les erreurs humaines,
- de livrer plus rapidement des fonctionnalités,
- de favoriser le travail en équipe.
Pourquoi .gitlab-ci.yml
est-il si important ?
GitLab intègre nativement un moteur de CI/CD, activable simplement avec un fichier .gitlab-ci.yml
à la racine du dépôt. Ce fichier contient la définition déclarative des étapes à exécuter (appelées jobs) organisées en stages.
Quelques exemples concrets d'automatisation avec ce fichier :
- Vérifier le formatage du code avec Prettier ou ESLint
- Lancer des tests unitaires avec Jest, PHPUnit ou Pytest
- Compiler un projet TypeScript ou Java
- Déployer une application sur un serveur ou dans le cloud
- Générer une documentation à chaque push
Aucun serveur externe n’est nécessaire : GitLab s’occupe de tout via ses GitLab Runners.
🛠️ Explication ou Étapes
1. Structure de base d’un fichier .gitlab-ci.yml
Voici la structure minimale d’un fichier .gitlab-ci.yml
:
1stages:
2 - build
3 - test
4 - deploy
5
6build_app:
7 stage: build
8 script:
9 - echo "Compilation de l'application"
10
11run_tests:
12 stage: test
13 script:
14 - echo "Lancement des tests"
15
16deploy_app:
17 stage: deploy
18 script:
19 - echo "Déploiement terminé"
stages
définit l’ordre des grandes étapes.- Chaque bloc (ex.
build_app
) représente un job à exécuter. stage
indique à quelle étape appartient le job.script
contient les commandes à exécuter.
GitLab exécutera les stages dans l’ordre, et les jobs en parallèle au sein d’un même stage si possible.
2. Déclencheurs et conditions d’exécution
On peut choisir quand et comment chaque job s’exécute avec des options comme only
, except
, rules
:
1run_tests:
2 stage: test
3 script:
4 - npm test
5 rules:
6 - if: '$CI_COMMIT_BRANCH == "main"'
Cela permet de n'exécuter certains jobs que dans des cas précis :
- Sur une branche donnée
- Lors d’un tag
- Si un fichier spécifique est modifié
- Si une variable est définie
3. Variables d’environnement
Les variables permettent d’éviter la duplication et de configurer dynamiquement les jobs :
1variables:
2 NODE_ENV: "production"
3
4build:
5 stage: build
6 script:
7 - echo "ENV: $NODE_ENV"
Elles peuvent aussi être définies dans l’interface GitLab en tant que variables secrètes (ex. tokens d’API, mots de passe).
4. Utilisation des artifacts
et cache
- Artifacts : fichiers générés par un job, disponibles pour téléchargement ou pour d’autres jobs.
- Cache : fichiers conservés entre les exécutions pour gagner du temps (ex. dépendances
node_modules
).
1build:
2 stage: build
3 script:
4 - npm install
5 cache:
6 paths:
7 - node_modules/
8 artifacts:
9 paths:
10 - dist/
5. Déploiement automatique
GitLab CI/CD permet de déployer un projet automatiquement :
1deploy_prod:
2 stage: deploy
3 only:
4 - tags
5 script:
6 - scp ./dist/* user@yourserver:/var/www/html/
Ici, le déploiement ne se fait que lors du push d’un tag, ce qui permet de contrôler finement les versions déployées.
6. Jobs en parallèle ou dépendants
Les jobs d’un même stage peuvent s’exécuter en parallèle :
1test_backend:
2 stage: test
3 script:
4 - npm run test:backend
5
6test_frontend:
7 stage: test
8 script:
9 - npm run test:frontend
Mais on peut aussi forcer des dépendances explicites avec needs
:
1generate_docs:
2 stage: deploy
3 script:
4 - npm run docs
5 needs:
6 - build_app
7. Inclusion de templates
Pour réutiliser du code ou structurer un projet plus complexe, GitLab propose des mécanismes d’inclusion :
1include:
2 - template: Node.js.gitlab-ci.yml
Ou des fichiers internes :
1include:
2 - local: 'ci/pipeline.test.yml'
8. Exécution conditionnelle selon les fichiers modifiés
Grâce à changes
, on peut éviter d'exécuter des jobs inutiles :
1lint_code:
2 stage: test
3 script: npm run lint
4 rules:
5 - changes:
6 - "**/*.ts"
9. Docker et GitLab CI
GitLab CI s’appuie sur des conteneurs Docker par défaut. Il est facile de spécifier une image à utiliser :
1image: node:20
2
3test:
4 stage: test
5 script:
6 - npm ci
7 - npm run test
Et on peut même définir plusieurs services Docker (ex. pour PostgreSQL, Redis...) :
1services:
2 - postgres:13
10. Pipelines manuels et environnement d’approbation
Pour des étapes critiques comme la production, on peut exiger un déclenchement manuel :
1deploy_production:
2 stage: deploy
3 script:
4 - ./deploy.sh
5 when: manual
Cela permet à un lead développeur ou devops de valider manuellement un déploiement.
💡 Exemples concrets
Exemple 1 : Pipeline complet pour une application Node.js
1image: node:20
2
3stages:
4 - install
5 - test
6 - build
7 - deploy
8
9install_dependencies:
10 stage: install
11 script:
12 - npm ci
13 cache:
14 paths:
15 - node_modules/
16
17unit_tests:
18 stage: test
19 script:
20 - npm test
21
22build_project:
23 stage: build
24 script:
25 - npm run build
26 artifacts:
27 paths:
28 - dist/
29
30deploy_to_staging:
31 stage: deploy
32 environment:
33 name: staging
34 only:
35 - develop
36 script:
37 - ./scripts/deploy-staging.sh
Exemple 2 : Projet PHP avec PHPUnit et Docker
1image: php:8.2
2
3services:
4 - mysql:5.7
5
6variables:
7 MYSQL_ROOT_PASSWORD: root
8 MYSQL_DATABASE: test_db
9
10before_script:
11 - apt-get update && apt-get install -y unzip zip git
12 - curl -sS https://getcomposer.org/installer | php
13 - php composer.phar install
14
15stages:
16 - test
17
18phpunit:
19 stage: test
20 script:
21 - vendor/bin/phpunit
Exemple 3 : Déploiement automatique via SSH
1deploy:
2 stage: deploy
3 only:
4 - main
5 script:
6 - scp -r ./dist/* deployer@yourserver:/var/www/html/
7 environment:
8 name: production
9 url: https://example.com
✅ Conclusion
Le fichier .gitlab-ci.yml
est le pivot de l’automatisation GitLab CI/CD. Grâce à lui, chaque étape de votre projet — du commit initial au déploiement final — peut être fiable, reproductible et transparente.
Même si sa syntaxe peut sembler complexe au départ, elle repose sur des principes simples, logiques et puissants : des jobs, des stages, des scripts, et des règles conditionnelles. En maîtrisant les fondamentaux, vous serez en mesure de structurer des pipelines adaptés à tout type de projet, qu’il s’agisse d’un site web statique, d’une API, ou d’une application monolithique complète.
À retenir :
- Un fichier
.gitlab-ci.yml
est obligatoire pour activer GitLab CI. - Il permet d’automatiser le build, les tests, le déploiement.
- Il peut intégrer des variables, caches, conditions et services externes.
- Il s’adapte à tout type de workflow et tout langage.