Pipelines multi-projet GitLab CI/CD (trigger downstream)

Votre application frontend doit déclencher le déploiement du backend après un build réussi ? Les pipelines multi-projet (trigger: project:) permettent de lancer le pipeline d'un autre projet depuis le vôtre. Vous pouvez propager des variables, attendre le résultat et construire des chaînes de déploiement entre projets indépendants.

Si les pipelines parent-enfant orchestrent des sous-pipelines dans le même projet (monorepo), les pipelines multi-projet orchestrent des projets différents qui ont chacun leur propre .gitlab-ci.yml.

Ce que vous allez apprendre

• Déclencher le pipeline d'un autre projet avec trigger: project:
• Propager des variables vers le projet cible
• Attendre le résultat du pipeline downstream avec strategy: depend
• Choisir entre parent-enfant et multi-projet selon votre architecture
• Sécuriser les déclenchements entre projets

Dans quel contexte ?

Vos projets GitLab sont découpés en repositories séparés (frontend, backend, infra, docs). Quand le backend change, vous devez relancer les tests d'intégration du frontend. Quand une image Docker est publiée, le projet de déploiement doit enchaîner.

Ce guide est fait pour vous si :

• Vous avez un projet API qui, après build, doit déclencher le déploiement
• Votre bibliothèque partagée doit tester les projets qui en dépendent
• Votre pipeline de release coordonne plusieurs microservices
• Vous voulez un pipeline d'intégration qui valide la compatibilité entre projets

Parent-enfant vs Multi-projet

Les deux mécanismes portent le même mot-clé trigger: et se confondent facilement, alors qu'ils ne répondent pas au même besoin. Le critère de choix tient en une question : le code déclenché vit-il dans le même dépôt ? Si oui, c'est du parent-enfant ; sinon, c'est du multi-projet, avec les contraintes de permissions et de propagation de variables qui vont avec.

Critère	Parent-enfant	Multi-projet
Scope	Même projet (même repo)	Projets différents (repos différents)
.gitlab-ci.yml	Le parent génère/référence les enfants	Chaque projet a son propre pipeline
Cas d'usage	Monorepo, sous-modules	Microservices, chaîne de déploiement
Syntaxe	trigger: include:	trigger: project:
Limites	Max 2 niveaux de profondeur	Pas de limite de chaîne
Variables	Héritage automatique	Propagation explicite

Glissez pour voir

→ Si votre code est dans un seul repo, utilisez parent-enfant (V2-07).

Déclencher un pipeline downstream

Le déclenchement repose sur un job particulier : il ne contient pas de script: mais une clé trigger: désignant le projet cible. GitLab appelle upstream le pipeline qui déclenche et downstream celui qui est déclenché. Trois réglages suffisent à couvrir la quasi-totalité des besoins : le projet visé, la branche, et le fait d'attendre ou non le résultat.

Syntaxe de base

Le chemin passé à project: est le chemin complet du dépôt dans GitLab (groupe, sous-groupe éventuel, puis nom du projet), pas son URL ni son identifiant numérique.

.gitlab-ci.yml du projet A (source)

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - npm run build

trigger:deploy:
  stage: deploy
  trigger:
    project: devops/deploy-service
    branch: main

Ce qui se passe :

1. Le pipeline du projet A exécute le job build
2. Le job trigger:deploy déclenche le pipeline du projet devops/deploy-service sur la branche main
3. Le pipeline de A continue sans attendre le résultat (par défaut)

Pas de section script

Un job trigger: ne peut pas avoir de script:. C'est un job déclencheur uniquement. Si vous avez besoin d'exécuter du code avant de déclencher, créez un job séparé dans le stage précédent.

Propager des variables

Pour transmettre des informations au projet cible, utilisez variables: :

Projet source

trigger:deploy:
  stage: deploy
  trigger:
    project: devops/deploy-service
    branch: main
  variables:
    UPSTREAM_PROJECT: $CI_PROJECT_PATH
    UPSTREAM_REF: $CI_COMMIT_REF_NAME
    UPSTREAM_SHA: $CI_COMMIT_SHORT_SHA
    APP_VERSION: $BUILD_VERSION

Le projet cible reçoit ces variables comme des variables d'environnement classiques :

Projet cible (devops/deploy-service)

deploy:
  stage: deploy
  script:
    - echo "Triggered by $UPSTREAM_PROJECT @ $UPSTREAM_SHA"
    - echo "Deploying version $APP_VERSION"
    - ./deploy.sh --version "$APP_VERSION"

Variables protégées

Les variables protégées du projet source ne sont pas transmises automatiquement au projet cible. Chaque projet gère ses propres secrets. C'est une mesure de sécurité : un projet ne peut pas accéder aux secrets d'un autre via un trigger.

Attendre le résultat : strategy: depend

Par défaut, le job trigger passe au statut success dès que le pipeline downstream est créé (pas terminé). Pour attendre :

trigger:deploy:
  stage: deploy
  trigger:
    project: devops/deploy-service
    branch: main
    strategy: depend
  variables:
    APP_VERSION: $BUILD_VERSION

Avec strategy: depend :

Statut downstream	Statut du job trigger
Succès	✅ Succès
Échec	❌ Échec
En cours	🔄 En attente

Glissez pour voir

C'est presque toujours ce que vous voulez. Sans strategy: depend, votre pipeline source affiche "succès" alors que le déploiement downstream a peut-être échoué.

Cibler une branche spécifique

Reprendre $CI_COMMIT_REF_NAME suppose qu'une branche du même nom existe dans le projet cible : sinon le déclenchement échoue, alors qu'une branche fixe reste toujours résolvable.

# Branche fixe
trigger:
  project: devops/deploy-service
  branch: main

# Même branche que le source (si elle existe dans le projet cible)
trigger:
  project: devops/deploy-service
  branch: $CI_COMMIT_REF_NAME

Branch par défaut

Si vous ne spécifiez pas branch:, GitLab déclenche le pipeline sur la branche par défaut du projet cible (généralement main).

Cas d'usage courants

Les trois situations qui suivent couvrent la majorité des usages rencontrés sur une organisation découpée en plusieurs dépôts. Elles se distinguent par le sens du déclenchement et par ce qu'on attend du pipeline downstream : coordonner une release, valider des consommateurs, ou simplement notifier.

Chaîne de déploiement microservices

Un projet orchestrateur, qui ne contient souvent qu'un .gitlab-ci.yml, déclenche les autres. Le rules: sur le tag garantit que rien ne part sur un simple commit de branche, et les jobs du même stage s'exécutent en parallèle.

Projet orchestrateur

stages:
  - trigger

trigger:api:
  stage: trigger
  trigger:
    project: team/api-service
    strategy: depend
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+/

trigger:frontend:
  stage: trigger
  trigger:
    project: team/frontend-app
    strategy: depend
  variables:
    API_VERSION: $CI_COMMIT_TAG
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+/

trigger:docs:
  stage: trigger
  trigger:
    project: team/documentation
  # Pas de strategy:depend : on n'attend pas les docs
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+/

Tester les dépendants d'une bibliothèque

Quand votre bibliothèque change, lancez les tests des projets qui l'utilisent :

Projet de la bibliothèque

test:library:
  stage: test
  script:
    - npm test

# Après les tests, vérifier que les consommateurs ne cassent pas
verify:app-a:
  stage: verify
  trigger:
    project: team/app-a
    strategy: depend
  variables:
    LIB_VERSION: $CI_COMMIT_SHA

verify:app-b:
  stage: verify
  trigger:
    project: team/app-b
    strategy: depend
  variables:
    LIB_VERSION: $CI_COMMIT_SHA

Pipeline inversé : le cible déclenche via l'API

Parfois c'est le projet cible qui doit écouter les changements du source. Utilisez un webhook ou un pipeline trigger token :

Projet source : déclencher via l'API dans un script

notify:deploy:
  stage: notify
  script:
    - |
      curl --request POST \
        --form "token=$DEPLOY_TRIGGER_TOKEN" \
        --form "ref=main" \
        --form "variables[UPSTREAM_SHA]=$CI_COMMIT_SHORT_SHA" \
        "https://gitlab.example.com/api/v4/projects/42/trigger/pipeline"

Préférez trigger: project:

L'approche curl + API fonctionne mais perd le lien visuel entre les pipelines dans l'interface GitLab. Utilisez trigger: project: quand c'est possible, GitLab affiche un lien cliquable vers le pipeline downstream.

Contrôle avec rules

Les jobs trigger supportent rules: comme tout autre job. C'est le moyen de n'ouvrir le déclenchement que dans les conditions voulues : la branche par défaut pour un environnement de staging, un tag de version pour la production. L'ajout de when: manual sur ce dernier impose une validation humaine avant que le pipeline downstream ne parte, et allow_failure: false garantit que son échec fera échouer le pipeline source.

trigger:staging:
  trigger:
    project: devops/deploy-service
    strategy: depend
  variables:
    ENVIRONMENT: staging
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

trigger:production:
  trigger:
    project: devops/deploy-service
    strategy: depend
  variables:
    ENVIRONMENT: production
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
      when: manual
      allow_failure: false

Permissions et sécurité

Un trigger multi-projet franchit une frontière : il fait exécuter du code dans un dépôt dont vous n'êtes pas forcément responsable. GitLab encadre cela par deux contrôles indépendants, l'un sur l'identité de l'utilisateur qui a lancé le pipeline source, l'autre sur la liste des projets autorisés à utiliser le jeton de job. Les deux doivent être satisfaits.

Qui peut déclencher quoi ?

Le pipeline downstream est créé au nom de l'utilisateur qui a déclenché le pipeline source. Cet utilisateur doit avoir au minimum le rôle Developer dans le projet cible.

Rôle dans le projet cible	Peut déclencher ?
Guest	❌
Reporter	❌
Developer	✅
Maintainer	✅
Owner	✅

Glissez pour voir

CI_JOB_TOKEN

Depuis GitLab 16.3+, le CI_JOB_TOKEN peut être utilisé pour l'authentification cross-projet. Configurez dans le projet cible : Settings > CI/CD > Token Access et ajoutez le projet source à la liste des projets autorisés.

Principe du moindre privilège

N'autorisez que les projets qui ont réellement besoin de déclencher votre pipeline. Révisez régulièrement la liste dans Token Access. Un projet compromis avec un accès trop large peut déclencher des déploiements non souhaités.

Limites et bonnes pratiques

Les pipelines multi-projet n'imposent presque aucune limite technique, ce qui est précisément le risque : rien n'empêche de construire une chaîne de six projets dont personne ne comprend plus l'ordre. Les contraintes réelles sont opérationnelles, et les quelques règles ci-dessous suffisent à garder l'ensemble lisible.

Limites

Retenez surtout la dernière ligne : ce n'est pas un plafond mais un comportement. Toute variable non listée dans variables: reste dans le projet source, y compris celles définies dans l'interface GitLab.

Limite	Valeur
Profondeur de chaîne downstream	Pas de limite stricte, mais chaque niveau ajoute de la latence
Pipelines simultanés par projet	Selon votre licence et la configuration du projet
Variables transmises	Pas de limite, mais seules les variables déclarées dans variables: sont propagées

Glissez pour voir

Bonnes pratiques

Ces cinq réflexes évitent les deux pannes les plus coûteuses en multi-projet : un déploiement qui se croit réussi, et un couplage entre dépôts que personne n'a documenté.

• Toujours utiliser strategy: depend sauf pour les triggers non critiques (docs, notifications)
• Nommer les jobs clairement : trigger:deploy-staging, pas downstream_1
• Propager le minimum de variables nécessaires, pas de secrets du projet source
• Documenter les dépendances entre projets dans le README
• Versionner via les tags : cibler branch: main pour le dernier état, un tag pour une version précise

Dépannage

La difficulté du multi-projet est que l'erreur se manifeste dans un dépôt et que sa cause se trouve dans l'autre. Commencez donc par regarder le pipeline downstream lui-même : s'il n'a jamais été créé, le problème relève des permissions ou du chemin de projet ; s'il existe mais échoue, c'est une affaire de variables ou de branche.

Symptôme	Cause probable	Solution
403 Forbidden	L'utilisateur n'a pas les droits sur le projet cible	Vérifier le rôle (minimum Developer)
Pipeline downstream non créé	Le projet cible n'existe pas ou est privé	Vérifier le chemin project: et les permissions
Job trigger "success" mais downstream en échec	strategy: depend non configuré	Ajouter strategy: depend
Variables non disponibles dans le downstream	Non déclarées dans variables:	Ajouter explicitement chaque variable à transmettre
Boucle infinie de triggers	Projet A trigger B qui trigger A	Ajouter une condition rules pour casser la boucle
Pipeline downstream sur la mauvaise branche	branch: absent	Spécifier branch: explicitement

Glissez pour voir

À retenir

• trigger: project: déclenche un pipeline dans un autre projet GitLab
• strategy: depend fait attendre le résultat, sans ça, le job trigger passe en succès dès la création
• Les variables doivent être propagées explicitement, pas d'héritage automatique
• L'utilisateur qui déclenche doit avoir le rôle Developer minimum dans le projet cible
• Parent-enfant = même repo (monorepo), multi-projet = repos différents (microservices)
• Les jobs trigger ne peuvent pas avoir de script:, c'est un déclencheur, pas un exécuteur
• Documentez toujours les dépendances entre projets, les triggers créent un couplage implicite

Testez vos connaissances

Ces questions portent uniquement sur les notions expliquées ci-dessus : déclenchement, propagation des variables, strategy: depend et permissions.

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

Workflows CI/CD Structurer vos pipelines pour MR, branches et releases.

Pipelines parent-enfant Orchestrer des sous-pipelines dans le même repo.

Pipelines dynamiques Générer du YAML à la volée selon le contexte.

×

📖 Voir la documentation →