Pipelines parent-enfant GitLab CI/CD

Votre pipeline a 50 jobs et devient ingérable ? Les pipelines parent-enfant permettent de découper un pipeline complexe en sous-pipelines indépendants. Le parent orchestre, les enfants exécutent.

En 30 secondes

# Pipeline parent
trigger_frontend:
  trigger:
    include: frontend/.gitlab-ci.yml
    strategy: depend    # Attend la fin de l'enfant

Le job trigger_frontend crée un pipeline enfant à partir du fichier frontend/.gitlab-ci.yml. Le parent attend sa fin grâce à strategy: depend.

Ce guide est fait pour vous si…

Monorepo complexe Frontend + Backend + API dans un seul repo.

Pipeline trop long Découper en sous-pipelines pour plus de clarté.

Multi-projets Déclencher des pipelines dans d'autres repos.

Passer des données Variables et artefacts entre parent et enfant.

Prérequis

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

• Concepts fondamentaux GitLab CI/CD
• DAG et parallélisme

Pourquoi des pipelines parent-enfant ?

Sans parent-enfant	Avec parent-enfant
Un seul .gitlab-ci.yml géant	Fichiers séparés par composant
Difficile à maintenir	Responsabilité claire
Tout s’exécute toujours	Exécution conditionnelle par composant
Un échec bloque tout	Isolation des problèmes

Glissez pour voir

Configuration de base

Pipeline parent

# .gitlab-ci.yml (racine du projet)

stages:
  - triggers

trigger_frontend:
  stage: triggers
  trigger:
    include: frontend/.gitlab-ci.yml
    strategy: depend

trigger_backend:
  stage: triggers
  trigger:
    include: backend/.gitlab-ci.yml
    strategy: depend

Pipeline enfant

frontend/.gitlab-ci.yml

stages:
  - build
  - test

build:
  stage: build
  script:
    - npm ci
    - npm run build

test:
  stage: test
  script:
    - npm test

Options de trigger

include : fichier local

trigger_job:
  trigger:
    include: path/to/child.yml

strategy: depend

Par défaut, le parent n’attend pas la fin de l’enfant. Avec strategy: depend :

• Le parent attend la fin de l’enfant
• Le statut du parent dépend du statut de l’enfant

trigger_job:
  trigger:
    include: child.yml
    strategy: depend    # ✅ Attend la fin

Sans strategy: depend

Sans cette option, le job parent passe immédiatement en success, même si l’enfant échoue ensuite. Utilisez toujours strategy: depend sauf cas particulier.

strategy: depend vs strategy: mirror

Strategy	Comportement
depend	Le parent attend l’enfant et hérite du statut
mirror	Le job trigger miroire le statut du downstream (utile avec auto-cancel)

Glissez pour voir

trigger_job:
  trigger:
    include: child.yml
    strategy: mirror    # Miroir strict du statut enfant

Recommandation GitLab

Pour les nouveaux projets, GitLab recommande strategy: mirror quand vous voulez un reflet strict du statut downstream.

forward : transmettre les variables

trigger_job:
  trigger:
    include: child.yml
    forward:
      yaml_variables: true      # Variables définies dans le YAML
      pipeline_variables: true  # Variables passées au pipeline (web, API)

Passer des variables à l’enfant

Variables explicites

trigger_frontend:
  variables:
    ENVIRONMENT: "staging"
    VERSION: $CI_COMMIT_SHA
  trigger:
    include: frontend/.gitlab-ci.yml
    strategy: depend

L’enfant peut utiliser $ENVIRONMENT et $VERSION.

Variables depuis un fichier dotenv

prepare:
  stage: prepare
  script:
    - echo "VERSION=1.2.3" >> build.env
  artifacts:
    reports:
      dotenv: build.env

trigger_deploy:
  stage: deploy
  needs: ["prepare"]
  variables:
    VERSION: $VERSION    # Provient de build.env
  trigger:
    include: deploy.yml
    strategy: depend

Passer des artefacts à l’enfant

Piège courant

Un pipeline enfant ne récupère pas automatiquement les artefacts du parent. Le needs classique ne fonctionne qu’au sein d’un même pipeline.

Pour récupérer des artefacts d’un pipeline amont, GitLab fournit des mécanismes dédiés.

Parent → Child (même projet) : needs:pipeline:job

Parent : produire un artefact + passer l’ID du pipeline au child.

build_artifacts:
  stage: build
  script:
    - echo "artifact from parent" > artifact.txt
  artifacts:
    paths:
      - artifact.txt

trigger_child:
  stage: deploy
  trigger:
    include: path/to/child-pipeline.yml
    strategy: depend
  variables:
    PARENT_PIPELINE_ID: $CI_PIPELINE_ID

Child : récupérer l’artefact depuis le pipeline amont.

test_child:
  stage: test
  script:
    - cat artifact.txt
  needs:
    - pipeline: $PARENT_PIPELINE_ID
      job: build_artifacts

Multi-projet : needs:project

Dans le pipeline aval :

test_downstream:
  stage: test
  script:
    - cat artifact.txt
  needs:
    - project: my/upstream_project
      job: build_artifacts
      ref: main
      artifacts: true

Job token scope

Pour needs:project, configurez l’accès via le job token scope allowlist côté projet amont (GitLab 15.9+).

Déclencher un pipeline dans un autre projet

Syntax project

trigger_other_project:
  trigger:
    project: group/other-project
    branch: main
    strategy: depend

Avec des variables

deploy_production:
  variables:
    DEPLOY_ENV: "production"
    APP_VERSION: $CI_COMMIT_TAG
  trigger:
    project: devops/deployment
    branch: main
    strategy: depend

Exemple monorepo

Structure :

monorepo/
├── .gitlab-ci.yml        # Parent
├── frontend/
│   ├── .gitlab-ci.yml    # Enfant frontend
│   └── src/
├── backend/
│   ├── .gitlab-ci.yml    # Enfant backend
│   └── src/
└── shared/
    └── utils/

Parent (racine)

.gitlab-ci.yml

stages:
  - prepare
  - build
  - deploy

# Déterminer ce qui a changé
changes:
  stage: prepare
  script:
    - |
      if git diff --name-only HEAD~1 | grep -q "^frontend/"; then
        echo "FRONTEND_CHANGED=true" >> build.env
      fi
      if git diff --name-only HEAD~1 | grep -q "^backend/"; then
        echo "BACKEND_CHANGED=true" >> build.env
      fi
  artifacts:
    reports:
      dotenv: build.env

# Déclencher frontend si modifié
trigger_frontend:
  stage: build
  needs: ["changes"]
  trigger:
    include: frontend/.gitlab-ci.yml
    strategy: depend
  rules:
    - if: $FRONTEND_CHANGED == "true"

# Déclencher backend si modifié
trigger_backend:
  stage: build
  needs: ["changes"]
  trigger:
    include: backend/.gitlab-ci.yml
    strategy: depend
  rules:
    - if: $BACKEND_CHANGED == "true"

Enfant frontend

frontend/.gitlab-ci.yml

stages:
  - install
  - build
  - test

install:
  stage: install
  script: npm ci
  cache:
    key: frontend-deps
    paths:
      - .npm/
  variables:
    npm_config_cache: '$CI_PROJECT_DIR/.npm'

build:
  stage: build
  script: npm run build
  artifacts:
    paths:
      - dist/

test:
  stage: test
  script: npm test

Détecter un pipeline enfant

Dans un pipeline enfant, $CI_PIPELINE_SOURCE prend des valeurs spécifiques :

• parent_pipeline : child pipeline (même projet)
• pipeline : multi-project pipeline

job_only_in_child:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "parent_pipeline"'
  script: echo "Runs only in child pipelines"

Limites et bonnes pratiques

Limites

Limite	Valeur
Profondeur child pipelines (parent → child → grandchild)	2 niveaux max
Taille de la hiérarchie downstream	1000 pipelines par défaut (paramétrable)
Fichiers include par child pipeline	3 fichiers max

Glissez pour voir

Limite d'include

Un child pipeline ne peut inclure que 3 fichiers de configuration (include:). Au-delà, vous obtenez une erreur de configuration. Consolidez vos templates si nécessaire.

Bonnes pratiques

1. Toujours strategy: depend sauf si vous voulez explicitement ne pas attendre

2. Un fichier CI par composant : frontend/.gitlab-ci.yml, backend/.gitlab-ci.yml

3. Conditions sur les triggers : ne déclenchez que ce qui a changé

4. Variables explicites : documentez ce que vous passez aux enfants

5. Nommez clairement : trigger_frontend, trigger_backend, pas job1, job2

Erreurs fréquentes

Erreur	Cause	Solution
Parent passe en success mais enfant échoue	Manque strategy: depend	Ajouter strategy: depend ou mirror
Variable non trouvée dans l’enfant	Variable non passée	Utiliser variables: ou forward:
maximum depth exceeded	Plus de 2 niveaux d’enfants	Restructurer le pipeline
Fichier enfant non trouvé	Mauvais chemin	Vérifier le chemin relatif
Artefacts non disponibles dans l’enfant	needs classique ne traverse pas les pipelines	Utiliser needs:pipeline:job
needs:project échoue	Job token non autorisé	Configurer allowlist côté projet amont

Glissez pour voir

À retenir

1. trigger: include crée un pipeline enfant à partir d’un fichier local
2. strategy: depend fait attendre le parent ; mirror pour un reflet strict
3. variables: passe des variables à l’enfant
4. Artefacts : utilisez needs:pipeline:job (parent→child) ou needs:project (multi-projet)
5. trigger: project déclenche un pipeline dans un autre projet
6. Limite : 2 niveaux de profondeur, 1000 pipelines downstream max
7. $CI_PIPELINE_SOURCE vaut parent_pipeline dans un child pipeline

Prochaines étapes

Pipelines dynamiques Générer des pipelines selon le contexte.

DAG et parallélisme Optimiser avec needs.

Templates Factoriser avec include et extends.

×

📖 Voir la documentation →