Débuter avec .gitlab-ci.yml pour automatiser vos projets

🧭 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.