GitLab CI : le fichier .gitlab-ci.yml

GitLab CI/CD est le système d'intégration continue intégré à GitLab : un fichier .gitlab-ci.yml à la racine du dépôt décrit un pipeline fait de stages (étapes) qui s'enchaînent et de jobs qui s'exécutent en parallèle à l'intérieur de chaque stage, sur des machines appelées runners. Les notions sont celles de GitHub Actions, la syntaxe change. Ce chapitre construit le pipeline de sorbier-frais pour GitLab, explique les mots-clés essentiels (rules, needs, artifacts, cache, services, environment) et donne la table d'équivalence avec GitHub Actions.

Le fichier et les runners

GitLab cherche un seul fichier, .gitlab-ci.yml, à la racine du dépôt. Chaque push, chaque merge request (le nom des pull requests chez GitLab) ou chaque tag peut créer un pipeline, visible dans le menu Build, Pipelines du projet.

Les jobs s'exécutent sur des runners :

• sur GitLab.com, des runners d'instance partagés, avec un quota mensuel de minutes de calcul selon l'offre ;
• dans une entreprise qui héberge son propre GitLab, des runners installés par l'équipe d'exploitation avec le programme GitLab Runner. Chaque runner a un exécuteur : docker (chaque job tourne dans un conteneur neuf, le cas le plus courant), shell (directement sur la machine), kubernetes…

Avec l'exécuteur docker, chaque job démarre dans l'image indiquée par image:. C'est une grande différence avec GitHub Actions : au lieu d'installer Node.js avec une action, on choisit une image qui le contient déjà, comme node:24.

Stages et jobs

stages:
  - test
  - build
  - deploy

lint:
  stage: test
  image: node:24
  script:
    - npm ci
    - npm run lint

tests-unitaires:
  stage: test
  image: node:24
  script:
    - npm ci
    - npm test -- --ci

image-docker:
  stage: build
  image: docker:29-cli
  services:
    - docker:29-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker build -t sorbier-frais:$CI_COMMIT_SHORT_SHA .

deploiement-recette:
  stage: deploy
  image: alpine:3.24
  script:
    - echo "Déploiement de la version $CI_COMMIT_SHORT_SHA en recette"

Les règles d'exécution :

1. Les stages s'exécutent dans l'ordre de la liste stages.
2. Les jobs d'un même stage tournent en parallèle.
3. Un stage ne démarre que si tous les jobs du stage précédent ont réussi.
4. Un job est un bloc de premier niveau avec un script ; son nom est libre, sauf les mots réservés (stages, variables, default, workflow, include…). Un nom qui commence par un point (.node) désigne un job caché, qui ne s'exécute pas et sert de modèle.

Sans liste stages, GitLab utilise build, test et deploy, dans cet ordre (plus .pre au tout début et .post à la toute fin).

Les mots-clés essentiels

Choisir quand un job tourne : rules

rules est une liste de conditions évaluées dans l'ordre : la première qui correspond décide. Si aucune ne correspond, le job n'est pas créé.

tests-unitaires:
  stage: test
  image: node:24
  script:
    - npm ci
    - npm test -- --ci
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"   # dans une merge request
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH        # sur la branche principale

deploiement-production:
  stage: deploy
  image: alpine:3.24
  script:
    - ./scripts/deployer.sh production
  rules:
    - if: $CI_COMMIT_TAG                                 # seulement pour un tag
      when: manual                                       # et après un clic

Les conditions lisent les variables prédéfinies de GitLab :

Éviter les pipelines en double. Comme avec GitHub, un push sur une branche qui a une merge request ouverte peut créer deux pipelines. Le bloc workflow décide, au niveau du pipeline entier, lequel garder :

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH
    - if: $CI_COMMIT_TAG

Lecture : un pipeline de merge request est toujours créé ; un push sur une branche qui a déjà une merge request ouverte n'en crée pas un second ; les autres push et les tags créent un pipeline.

needs : ne pas attendre tout le stage

Par défaut, un job attend la fin de tout le stage précédent. needs le fait démarrer dès que les jobs qu'il cite ont réussi : le pipeline devient un graphe (DAG, directed acyclic graph) au lieu d'une suite de colonnes.

audit-dependances:
  stage: deploy
  image: node:24
  needs: [tests-unitaires]       # démarre dès la fin de tests-unitaires
  script:
    - npm audit --audit-level=high

needs: [] (liste vide) fait démarrer le job immédiatement, au tout début du pipeline. needs transmet aussi les artefacts : un job ne télécharge que les artefacts des jobs cités.

Artefacts, rapports et cache

tests-unitaires:
  stage: test
  image: node:24
  variables:
    npm_config_cache: "$CI_PROJECT_DIR/.npm"
  cache:
    key:
      files:
        - package-lock.json      # la clé change quand les dépendances changent
    paths:
      - .npm/
  script:
    - npm ci --prefer-offline
    - npm test -- --ci --coverage
  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
  artifacts:
    when: always                 # même si les tests échouent
    expire_in: 1 week
    paths:
      - coverage/
    reports:
      junit: reports/junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

• cache garde le dossier .npm/ entre les pipelines ; la variable npm_config_cache dit à npm de l'utiliser. GitLab ne met en cache que des dossiers situés dans le projet.
• artifacts:paths conserve coverage/ pendant une semaine ; when: always l'envoie même en cas d'échec.
• artifacts:reports:junit fait afficher le détail des tests (réussis, échoués, durée) dans la merge request ; coverage_report colore les lignes couvertes dans le diff.
• coverage est une expression régulière que GitLab applique au journal du job pour extraire le pourcentage de couverture et l'afficher dans la merge request ; celle-ci correspond au résumé affiché par Jest.

Pour produire reports/junit.xml et coverage/cobertura-coverage.xml, Jest a besoin du rapporteur jest-junit et du format de couverture cobertura (chapitre 6).

Une base de données pour les tests : services

tests-integration:
  stage: test
  image: node:24
  services:
    - name: mysql:8.4
      alias: mysql
  variables:
    MYSQL_ROOT_PASSWORD: root
    MYSQL_DATABASE: frais_test
    DB_HOST: mysql
    DB_USER: root
    DB_PASSWORD: root
    DB_NAME: frais_test
  script:
    - npm ci
    - npm run test:integration

GitLab démarre un conteneur mysql:8.4 à côté du job ; il est joignable sous le nom de son alias, ici mysql. Les variables du job sont aussi transmises au service, ce qui initialise la base frais_test. Le mot de passe root n'est pas un secret : la base est vide, jetable, et inaccessible hors du job.

Environnements et déploiement manuel

deploiement-recette:
  stage: deploy
  image: alpine:3.24
  environment:
    name: recette
    url: https://recette.sorbier.example
  script:
    - ./scripts/deployer.sh recette
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploiement-production:
  stage: deploy
  image: alpine:3.24
  needs: [deploiement-recette]
  environment:
    name: production
    url: https://frais.sorbier.example
  script:
    - ./scripts/deployer.sh production
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual

environment enregistre chaque déploiement dans le menu Operate, Environments : on voit quelle version tourne où, et un bouton permet de redéployer une version précédente. when: manual affiche un bouton de lecture sur le job : le pipeline s'arrête sur ce job tant que personne ne clique, ce qui est une livraison continue. Les offres payantes de GitLab ajoutent les environnements protégés, où seules certaines personnes peuvent lancer le déploiement.

Réutiliser la configuration : extends, default et include

Les jobs Node.js répètent la même image et la même installation. Un job caché sert de modèle :

.node:
  image: node:24
  before_script:
    - npm ci

lint:
  extends: .node
  stage: test
  script:
    - npm run lint

tests-unitaires:
  extends: .node
  stage: test
  script:
    - npm test -- --ci

• extends fusionne le modèle dans le job ; le job peut redéfinir n'importe quelle clé.
• default: donne des valeurs à tous les jobs (default: { image: node:24 }).
• include: importe d'autres fichiers : un fichier du projet (include: { local: ci/tests.yml }), d'un autre projet, ou un modèle fourni par GitLab, comme l'analyse de sécurité du code (include: [{ template: Jobs/SAST.gitlab-ci.yml }], chapitre 7).

Équivalences entre GitHub Actions et GitLab CI

Et Jenkins ?

Jenkins est le plus ancien des serveurs d'intégration continue encore très utilisés. On l'installe soi-même ; le pipeline est décrit dans un Jenkinsfile écrit dans un langage dérivé de Groovy :

pipeline {
    agent { docker { image 'node:24' } }   // nécessite le plugin Docker Pipeline
    stages {
        stage('Installer') { steps { sh 'npm ci' } }
        stage('Lint')      { steps { sh 'npm run lint' } }
        stage('Tests')     { steps { sh 'npm test -- --ci' } }
    }
    post {
        always { junit 'reports/junit.xml' }  // publie le rapport de tests
    }
}

On y retrouve les mêmes idées : des étapes ordonnées, des commandes, un rapport publié même en cas d'échec. Jenkins est très souple grâce à ses milliers d'extensions, mais il faut maintenir le serveur, ses mises à jour et la sécurité de ses extensions.

Exercices

stages: [test, build, deploy]

lint:
  stage: test
  script: [npm run lint]
tests:
  stage: test
  script: [npm test]
construction:
  stage: build
  script: [docker build -t app .]
audit:
  stage: deploy
  needs: [tests]
  script: [npm audit --audit-level=high]
recette:
  stage: deploy
  script: [./deployer.sh recette]

name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npm run lint
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npm test

stages:
  - test

.node:
  image: node:24
  before_script:
    - npm ci
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

lint:
  extends: .node
  stage: test
  script:
    - npm run lint

tests:
  extends: .node
  stage: test
  script:
    - npm test

deploiement-production:
  stage: deploy
  script:
    - ./deployer.sh production
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_TAG
      when: never

  rules:
    - if: $CI_COMMIT_TAG
      when: manual