Conditions d'exécution GitLab CI/CD (rules)

Votre pipeline lance tous les jobs à chaque commit, même quand ce n’est pas nécessaire ? Les rules permettent de contrôler précisément quand un job s’exécute — sur quelle branche, pour quel type de changement, avec quelle approbation.

Ce guide vous montre comment optimiser vos pipelines en exécutant uniquement ce qui est nécessaire, et comment éviter le piège classique des pipelines qui “skip” sans raison apparente.

En 30 secondes

deploy:
  script: ./deploy.sh
  rules:
    # Déploie sur main uniquement, après validation manuelle
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
    # Sinon, n'exécute jamais ce job
    - when: never

La première règle qui matche gagne. Si aucune règle ne matche, le job est ignoré.

Ce guide est fait pour vous si…

Vous voulez limiter l'exécution Job uniquement sur main, ou sur certains fichiers modifiés.

Vous avez besoin d'approbation Déploiement manuel, ou différé de X minutes.

Votre pipeline skip sans raison Comprendre workflow:rules vs rules.

Vous optimisez les ressources Ne pas rebuilder si seul le README change.

Prérequis

Avant de continuer, assurez-vous de maîtriser :

• Variables GitLab CI/CD (les rules utilisent des variables)
• Structure de base d’un .gitlab-ci.yml

Pourquoi les rules sont essentielles

Sans rules, tous les jobs s’exécutent à chaque pipeline. C’est un gaspillage de ressources et de temps :

• Tests complets alors que seul le README a changé
• Build Docker alors que le code n’a pas bougé
• Déploiement automatique sans validation humaine

Les rules permettent d’exécuter uniquement ce qui est nécessaire, quand c’est nécessaire.

Les règles de base : if, changes, exists

if : condition sur une variable

La règle la plus utilisée. Teste une expression qui renvoie vrai ou faux.

job:
  script: echo "Déploiement"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Opérateurs disponibles :

Opérateur	Signification	Exemple
==	Égal à	$VAR == "value"
!=	Différent de	$VAR != "skip"
=~	Match regex	$VAR =~ /^feature-/
!~	Ne match pas regex	$VAR !~ /wip/
&&	ET logique	$A == "x" && $B == "y"
`		`

Glissez pour voir

Variables les plus utilisées dans les rules :

Variable	Valeur	Cas d’usage
$CI_COMMIT_BRANCH	Nom de la branche	Limiter à main, develop
$CI_COMMIT_TAG	Nom du tag (si tag)	Déployer uniquement les releases
$CI_PIPELINE_SOURCE	Source du pipeline	push, merge_request_event, schedule
$CI_MERGE_REQUEST_ID	ID de la MR	Jobs spécifiques aux MRs

Glissez pour voir

# Exemples pratiques
rules:
  # Sur la branche main uniquement
  - if: '$CI_COMMIT_BRANCH == "main"'

  # Sur un tag de release (v1.0.0, v2.3.4...)
  - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'

  # Uniquement pour les merge requests
  - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

  # Pipeline planifié (cron)
  - if: '$CI_PIPELINE_SOURCE == "schedule"'

changes : condition sur les fichiers modifiés

Exécute le job uniquement si certains fichiers ont été modifiés dans le commit.

build_frontend:
  script: npm run build
  rules:
    - changes:
        - "frontend/**/*"
        - "package.json"
        - "package-lock.json"

Patterns supportés :

Pattern	Signification
src/*.js	Fichiers .js dans src/
src/**/*.js	Fichiers .js dans src/ et sous-dossiers
*.md	Fichiers .md à la racine
**/*.md	Tous les fichiers .md du projet

Glissez pour voir

Pièges avec changes

changes a des comportements qui peuvent surprendre :

• Toujours vrai sur les pipelines schedule ou web (tous les fichiers considérés modifiés)
• Toujours vrai lors du push d’une nouvelle branche ou d’un nouveau tag (pas de base de comparaison)
• Sur d’autres sources (manual, api), changes peut être vrai si aucune base de comparaison n’existe

Bonne pratique : combinez changes avec un if: qui limite aux sources pertinentes :

rules:
  - if: '$CI_PIPELINE_SOURCE == "push" || $CI_PIPELINE_SOURCE == "merge_request_event"'
    changes:
      - "src/**/*"
  - when: never

exists : condition sur l’existence d’un fichier

Exécute le job si un fichier existe dans le repository.

docker_build:
  script: docker build -t myapp .
  rules:
    - exists:
        - Dockerfile

Utile pour les monorepos où tous les projets n’ont pas les mêmes fichiers.

Combiner les conditions

Vous pouvez combiner if, changes et exists dans une même règle :

deploy_docs:
  script: ./deploy-docs.sh
  rules:
    # Sur main ET si des fichiers docs ont changé
    - if: '$CI_COMMIT_BRANCH == "main"'
      changes:
        - "docs/**/*"
        - "mkdocs.yml"

Attention : dans une règle, les conditions sont en ET. Pour un OU, utilisez plusieurs règles :

job:
  rules:
    # Sur main OU sur un tag de release
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_TAG =~ /^v\d+/'

Contrôler le déclenchement avec when

when définit comment le job démarre si la règle matche.

Les valeurs de when

Valeur	Comportement
on_success	Démarre automatiquement si les jobs précédents ont réussi (défaut)
on_failure	Démarre uniquement si un job précédent a échoué
always	Démarre toujours, quel que soit le résultat des jobs précédents
manual	Attend un clic dans l’interface pour démarrer
delayed	Démarre automatiquement après un délai
never	Ne démarre jamais (exclut le job)

Glissez pour voir

Exemples pratiques

Déploiement manuel en production :

deploy_prod:
  script: ./deploy.sh production
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual

Notification en cas d’échec :

notify_failure:
  script: ./send-slack-alert.sh
  rules:
    # Condition explicite + when: on_failure
    - if: '$CI_PIPELINE_SOURCE'
      when: on_failure

Déploiement différé (canary) :

deploy_canary:
  script: ./deploy.sh canary
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: delayed
      start_in: 30 minutes

Exclure explicitement :

heavy_tests:
  script: ./run-all-tests.sh
  rules:
    # Pas sur les branches WIP
    - if: '$CI_COMMIT_BRANCH =~ /^wip-/'
      when: never
    # Sinon, exécuter normalement
    - when: on_success

La règle d'or

La première règle qui matche gagne. Mettez les exclusions (when: never) en premier, puis les cas spéciaux, puis le cas par défaut.

workflow:rules : contrôler le pipeline entier

workflow:rules détermine si le pipeline lui-même doit être créé. C’est différent des rules au niveau des jobs qui contrôlent chaque job individuellement.

Pourquoi c’est important

Sans workflow:rules, GitLab crée un pipeline pour chaque push, même si aucun job ne doit s’exécuter. Cela crée du bruit dans l’interface.

Avec workflow:rules, vous pouvez empêcher la création du pipeline dans certains cas.

Exemple : éviter les pipelines en double

workflow:
  rules:
    # Pas de pipeline si c'est un tag (on déploie via autre workflow)
    - if: '$CI_COMMIT_TAG'
      when: never
    # Pas de pipeline si la branche a une MR ouverte
    # (le pipeline MR suffit)
    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
      when: never
    # Pour les merge requests
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    # Pour les pushs sur les branches
    - if: '$CI_COMMIT_BRANCH'

À propos des tags

L’exemple ci-dessus exclut les pipelines sur tags (when: never). C’est adapté uniquement si vous avez un autre mécanisme de déploiement pour les releases.

Si vous publiez par tag, supprimez cette règle ou inversez-la pour autoriser les pipelines sur tags.

Le piège classique : pipeline qui “skip”

Symptôme : vous poussez du code, le pipeline apparaît comme “skipped” ou ne démarre pas du tout.

Cause probable : workflow:rules empêche la création du pipeline.

Diagnostic :

1. Vérifiez votre section workflow:rules
2. Identifiez quelle règle matche avec vos conditions actuelles
3. Si aucune règle ne matche, le pipeline est skipped

# ❌ Problème : ce workflow ne matche jamais pour les pushs simples
workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

# ✅ Solution : ajouter les autres cas
workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH'

Exemples pratiques

Pipeline optimisé par type de changement

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_TAG'

stages:
  - lint
  - build
  - test
  - deploy

# Lint : toujours (rapide, peu coûteux)
lint:
  stage: lint
  script: npm run lint

# Build : seulement si le code a changé
build:
  stage: build
  script: npm run build
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" || $CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - "src/**/*"
        - "package*.json"

# Tests : seulement si le code a changé
test:
  stage: test
  script: npm test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" || $CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - "src/**/*"
        - "tests/**/*"
        - "package*.json"

# Deploy staging : auto sur main
deploy_staging:
  stage: deploy
  script: ./deploy.sh staging
  environment:
    name: staging
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

# Deploy prod : manuel sur tags
deploy_prod:
  stage: deploy
  script: ./deploy.sh production
  environment:
    name: production
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v\d+/'
      when: manual

Éviter les exécutions redondantes

workflow:
  rules:
    # Un tag déclenche son propre pipeline, pas besoin du push
    - if: '$CI_COMMIT_TAG'
    # Pour les MRs, utiliser le pipeline MR
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    # Pour les pushs sur branches sans MR ouverte
    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
      when: never
    - if: '$CI_COMMIT_BRANCH'

Erreurs fréquentes

Symptôme	Cause probable	Solution
Pipeline entier “skipped”	workflow:rules ne matche pas	Ajouter une règle pour votre cas
Job jamais exécuté	Ordre des règles (never en dernier)	Mettre les exclusions en premier
Job toujours exécuté	Pas de règle, comportement par défaut	Ajouter rules: explicites
changes toujours vrai	Pipeline schedule ou web	changes ne fonctionne qu’avec push/MR
Variables non définies dans rules	Variable inexistante	Tester avec $VAR (vide = faux)

Glissez pour voir

Piège courant : variables de jobs

Les rules sont évaluées au moment où GitLab construit le pipeline, donc avant l’exécution des jobs.

Vous ne pouvez pas utiliser dans rules des variables générées par des scripts de jobs (ex: variables dotenv, artifacts:reports:dotenv). Ces variables n’existent pas encore quand GitLab décide quels jobs inclure.

Déboguer les rules

Ajoutez un job de debug pour voir les variables :

debug:
  script:
    - echo "BRANCH=$CI_COMMIT_BRANCH"
    - echo "SOURCE=$CI_PIPELINE_SOURCE"
    - echo "TAG=$CI_COMMIT_TAG"
    - echo "MR=$CI_MERGE_REQUEST_ID"
  rules:
    - if: '$CI_PIPELINE_SOURCE'
      when: always

Attention : n’utilisez jamais printenv ou env en production — cela peut exposer des secrets dans les logs.

Migrer depuis only/except

Si vous avez des pipelines avec only/except, migrez vers rules (plus flexible et plus clair).

# ❌ Ancien style (deprecated)
deploy:
  script: ./deploy.sh
  only:
    - main
  except:
    - schedules

# ✅ Nouveau style
deploy:
  script: ./deploy.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: never
    - if: '$CI_COMMIT_BRANCH == "main"'

À retenir

1. rules contrôle quand un job s’exécute, workflow:rules contrôle quand le pipeline est créé.
2. Première règle qui matche gagne — ordonnez vos règles du plus spécifique au plus général.
3. if teste des variables, changes teste les fichiers modifiés, exists teste l’existence.
4. when: never en premier pour exclure, when: on_success en dernier par défaut.
5. changes ne fonctionne pas avec les pipelines schedule ou web.
6. Pipeline “skipped” = vérifier workflow:rules en premier.

Testez vos connaissances

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

5 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Prochaines étapes

Déclencheurs Push, MR, tags, schedules — maîtriser CI_PIPELINE_SOURCE.

Environnements Déployer sur dev, staging, prod avec rules et environnements.

Dépannage : pourquoi ça skip Diagnostic complet des pipelines qui ne démarrent pas.

×

📖 Voir la documentation →