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

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

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é)

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

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

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

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

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

Configuration dans GitLab

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

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

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

Déclencher un pipeline

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

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

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é

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

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

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 →