Déclencheurs de pipelines GitLab CI/CD

Votre pipeline tourne deux fois sur chaque commit ? C'est le piège classique : un pipeline sur la branche ET un sur la merge request. Ce guide vous apprend à contrôler précisément quand vos pipelines s'exécutent grâce aux sources de pipeline et à CI_PIPELINE_SOURCE.

En 30 secondes

workflow:
  rules:
    # Pipeline MR uniquement (pas de doublon)
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # Pipeline sur main (après merge)
    - if: $CI_COMMIT_BRANCH == "main"
    # Tags de release
    - if: $CI_COMMIT_TAG

Cette configuration évite les doublons : pipeline MR pendant la review, pipeline branch uniquement sur main.

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Comprendre CI_PIPELINE_SOURCE : identifier comment un pipeline a été déclenché
• Éviter les doublons branch/MR : configurer workflow:rules pour un seul pipeline
• Configurer des schedules : exécuter des jobs de nuit ou périodiques
• Cibler les tags : déclencher des releases sur les tags de version
• Déclencher via API : lancer un pipeline depuis un script externe
• Adapter les variables : gérer les différences entre sources de pipeline

Prérequis

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

• Rules et conditions
• Variables prédéfinies

Les sources de pipeline (CI_PIPELINE_SOURCE)

Chaque pipeline a une source qui indique comment il a été déclenché :

Source	Déclencheur	Cas d'usage
push	Commit poussé sur une branche	Pipeline standard
merge_request_event	Création/mise à jour d'une MR	Review, tests pré-merge
schedule	Cron configuré dans GitLab	Tests de nuit, scans
web	Bouton "Run pipeline" dans l'UI	Debug, déploiement manuel
api	Appel API /pipeline	Automatisation externe
trigger	trigger: depuis un autre pipeline	Multi-projet
parent_pipeline	Child pipeline	Parent-enfant
pipeline	Downstream multi-projet	Orchestration

Glissez pour voir

Utiliser CI_PIPELINE_SOURCE dans les rules

La variable est disponible dans tous les pipelines, quelle que soit la source : c'est le seul critère qui fonctionne aussi bien dans workflow:rules que dans les rules: d'un job.

job_only_on_mr:
  script: echo "Tests pré-merge"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

job_only_on_schedule:
  script: echo "Scan de sécurité nocturne"
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

job_only_on_tag:
  script: echo "Release"
  rules:
    - if: $CI_COMMIT_TAG

Éviter les doublons branch/MR

C'est le symptôme qui amène la plupart des lecteurs sur cette page : deux pipelines identiques par commit, deux fois les minutes de runner consommées, et une liste de pipelines illisible. La cause n'est pas un bug, c'est le comportement par défaut quand le fichier .gitlab-ci.yml ne contient aucun workflow:rules. Deux corrections existent, la première convient à la grande majorité des projets.

Le problème

Par défaut, quand vous créez une MR, GitLab peut créer deux pipelines :

1. Un pipeline branch (source: push)
2. Un pipeline MR (source: merge_request_event)

C'est du gaspillage de ressources et ça pollue l'interface.

Solution 1 : Pipeline MR uniquement (recommandé)

Les règles de workflow: sont évaluées de haut en bas et la première qui correspond décide du sort du pipeline. Un commit poussé sur une branche de travail ne correspond à aucune des trois conditions : aucun pipeline branch n'est créé.

workflow:
  rules:
    # Pipelines MR pour toutes les branches avec MR ouverte
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # Pipeline branch uniquement sur main (après merge)
    - if: $CI_COMMIT_BRANCH == "main"
    # Tags de release
    - if: $CI_COMMIT_TAG

Avantage

Cette approche garantit qu'un seul pipeline tourne pendant la review (le pipeline MR). Le pipeline branch ne tourne que sur main après le merge.

Solution 2 : Utiliser CI_OPEN_MERGE_REQUESTS

Cette variante conserve un pipeline sur les branches tant qu'aucune MR n'est ouverte, puis bascule sur le pipeline MR dès qu'une revue démarre. Le when: never en tête est ce qui supprime le doublon.

workflow:
  rules:
    # Si une MR est ouverte, laisser le pipeline MR s'en charger
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    # Pipeline MR
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # Pipeline branch (si pas de MR ouverte)
    - if: $CI_COMMIT_BRANCH

CI_OPEN_MERGE_REQUESTS

Cette variable contient la liste des MR ouvertes pour ce commit. Elle n'est disponible que si "Pipelines for merge requests" est activé dans les settings du projet.

Comparaison des approches

Le choix dépend d'une seule question : voulez-vous que les commits poussés sur une branche sans MR ouverte déclenchent des tests ?

Approche	Avantage	Inconvénient
MR uniquement	Simple, clair	Pas de pipeline sur branches sans MR
CI_OPEN_MERGE_REQUESTS	Pipeline branch si pas de MR	Plus complexe

Glissez pour voir

Pipelines de tags

Les tags sont souvent utilisés pour les releases. Ciblez-les spécifiquement :

release:
  stage: deploy
  script:
    - echo "Building release $CI_COMMIT_TAG"
    - ./build-release.sh
  rules:
    - if: $CI_COMMIT_TAG

Variables utiles pour les tags

Dans un pipeline de tag, CI_COMMIT_BRANCH est vide : le tag ne pointe pas vers une branche. Les variables ci-dessous sont celles sur lesquelles s'appuyer pour construire un numéro de version ou vérifier une protection.

Variable	Contenu
CI_COMMIT_TAG	Nom du tag (ex: v1.2.3)
CI_COMMIT_REF_NAME	Tag ou branche
CI_COMMIT_REF_PROTECTED	true si tag/branche protégé

Glissez pour voir

Pattern matching sur les tags

Les expressions régulières s'écrivent entre barres obliques, sans guillemets, et sont ancrées explicitement avec ^ et $ : sans ancres, v1.0.0-rc1 correspondrait aussi au motif des versions finales.

release_production:
  rules:
    # Tags de release (v1.0.0, v2.1.3, etc.)
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/

release_prerelease:
  rules:
    # Tags de prérelease (v1.0.0-rc1, v2.0.0-beta)
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+-.+$/

Pipelines schedulés

Un pipeline schedulé ne se déclare pas dans le fichier .gitlab-ci.yml mais dans l'interface du projet : le fichier ne fait que réagir à la source schedule. C'est le mécanisme des scans de sécurité nocturnes, des rapports périodiques et des tâches de maintenance, tout ce qui ne doit pas dépendre d'un commit.

Configuration dans GitLab

Le planning est attaché à une branche cible et s'exécute avec les droits de son créateur : si cette personne perd l'accès à la branche protégée, le planning cesse silencieusement de fonctionner.

1. Accéder aux schedules

   Build > Pipeline schedules > New schedule

2. Configurer le cron

   • Description : "Scan de sécurité nocturne"
   • Interval pattern : 0 2 * * * (tous les jours à 2h)
   • Target branch : main

3. Ajouter des variables (optionnel)

   • SCAN_TYPE = full
   • Ces variables sont disponibles dans le pipeline

Cibler les jobs schedulés

Les variables définies dans le planning écrasent celles du job. Déclarer une valeur par défaut au niveau du job, comme SCAN_TYPE ci-dessous, évite que le script reçoive une variable vide lors d'une exécution manuelle.

security_scan:
  stage: test
  script:
    - ./security-scan.sh --type $SCAN_TYPE
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  variables:
    SCAN_TYPE: "quick"  # Valeur par défaut si non définie

Patterns de schedules utiles

GitLab utilise la syntaxe cron standard à cinq champs, interprétée dans le fuseau horaire configuré pour l'instance. Voici les rythmes les plus courants.

Cron	Description
0 2 * * *	Tous les jours à 2h
0 2 * * 1-5	Lun-Ven à 2h
0 */6 * * *	Toutes les 6 heures
0 0 * * 0	Dimanche minuit
0 0 1 * *	Premier jour du mois

Glissez pour voir

Déclenchement via API

Le déclenchement externe sert à relier GitLab à ce qui vit en dehors : un outil de release, un autre dépôt, un système de tickets. Deux chemins existent et ils ne produisent pas la même valeur de CI_PIPELINE_SOURCE, ce qui a des conséquences directes sur vos rules:.

Déclencher un pipeline

L'appel accepte des variables via la syntaxe variables[NOM]=valeur, qui arrivent dans le pipeline comme des variables CI ordinaires. L'option --fail fait échouer curl sur une réponse HTTP d'erreur, sans quoi un token invalide passerait inaperçu dans un script.

curl -X POST \
  --fail \
  -F "token=$TRIGGER_TOKEN" \
  -F "ref=main" \
  -F "variables[DEPLOY_ENV]=staging" \
  "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline"

Créer un trigger token

Le token n'est affiché qu'à sa création : s'il est perdu, il faut en générer un nouveau et mettre à jour tous les appelants.

1. Settings > CI/CD > Pipeline trigger tokens
2. Add new token
3. Copier le token (affiché une seule fois)

Job qui détecte un déclenchement API

Tester les deux sources dans la même condition évite d'avoir à savoir quel mécanisme d'appel a été utilisé côté client.

deploy_from_api:
  script:
    - echo "Déploiement déclenché via API"
    - echo "Environnement: $DEPLOY_ENV"
  rules:
    - if: $CI_PIPELINE_SOURCE == "trigger" || $CI_PIPELINE_SOURCE == "api"

trigger vs api

• api : pipeline lancé via l'API /pipeline
• trigger : pipeline lancé via un trigger token

Variables selon la source

Certaines variables ne sont disponibles que pour certaines sources :

Variable	push	merge_request_event	schedule
CI_COMMIT_BRANCH	✅	❌	✅
CI_MERGE_REQUEST_IID	❌	✅	❌
CI_MERGE_REQUEST_SOURCE_BRANCH_NAME	❌	✅	❌
CI_PIPELINE_SOURCE	✅	✅	✅
CI_OPEN_MERGE_REQUESTS	✅	❌	✅

Glissez pour voir

Piège MR

Dans un pipeline MR, CI_COMMIT_BRANCH n'existe pas. Utilisez CI_MERGE_REQUEST_SOURCE_BRANCH_NAME à la place.

Workflow complet recommandé

Cet exemple rassemble les cinq cas traités jusqu'ici dans un seul fichier. Le bloc workflow: filtre en amont : un pipeline qui ne correspond à aucune de ses règles n'est jamais créé, et les rules: des jobs n'ont donc plus qu'à distinguer les cas restants. C'est aussi pourquoi le job test n'a aucune règle : tout ce qui arrive jusqu'à lui a déjà été validé par workflow:.

workflow:
  rules:
    # 1. Pipelines MR (review)
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # 2. Branches protégées (après merge)
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_BRANCH == "develop"
    # 3. Tags de release
    - if: $CI_COMMIT_TAG
    # 4. Schedules (scans nocturnes)
    - if: $CI_PIPELINE_SOURCE == "schedule"
    # 5. Déclenchement manuel/API
    - if: $CI_PIPELINE_SOURCE == "web"
    - if: $CI_PIPELINE_SOURCE == "api"

# Jobs conditionnels selon la source
test:
  stage: test
  script: npm test
  # Tourne toujours (workflow l'a déjà filtré)

security_scan:
  stage: test
  script: ./security-scan.sh
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual
      allow_failure: true

deploy_staging:
  stage: deploy
  script: ./deploy.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

release:
  stage: deploy
  script: ./release.sh
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/

Erreurs fréquentes

Ces cinq situations couvrent l'essentiel des tickets ouverts sur le sujet. Le point commun des trois premières : le pipeline se comporte comme prévu, c'est la compréhension de la source qui est fausse.

Erreur	Cause	Solution
Pipeline tourne 2 fois	Pas de workflow:rules pour filtrer	Ajouter workflow MR-first
CI_COMMIT_BRANCH vide	Pipeline MR	Utiliser CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
Schedule ne tourne pas	Branch protégée sans permission	Vérifier les permissions du créateur
Tag non détecté	rules: trop restrictives	Ajouter if: $CI_COMMIT_TAG
API retourne 401	Token invalide	Régénérer le trigger token

Glissez pour voir

À retenir

Concept	Clé
Source de pipeline	CI_PIPELINE_SOURCE identifie le déclencheur
Doublons	workflow:rules MR-first évite 2 pipelines
Schedules	Pour scans nocturnes, maintenance périodique
Tags	$CI_COMMIT_TAG pour les releases
Variables MR	CI_COMMIT_BRANCH n'existe pas, utiliser CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
MR ouverte	CI_OPEN_MERGE_REQUESTS liste les MR pour ce commit

Glissez pour voir

On passe à la pratique

Passez au Lab 08, Déclencher pipeline pour configurer schedules, triggers et API.

Contrôle des connaissances

Testez vos connaissances sur les déclencheurs de pipelines GitLab.

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

Environnements Déployer vers dev, staging, production.

Rules avancées Conditions complexes et workflow:rules.

Pipelines parent-enfant Orchestrer des sous-pipelines.

×

📖 Voir la documentation →