TopolearnMonorepos and multi-service systems outgrow one flat pipeline; downstream pipelines keep them manageable.
A trigger job starts another pipeline instead of running a script.
- Parent-child pipelines run in the same project:
trigger: include: path/to/child.yml. Each child has its own stages and jobs, so a monorepo can have one child per service, each started only when its files change (rules: changes). - Multi-project pipelines start a pipeline in another project:
trigger: project: acme/deployerwith an optionalbranch. Useful when an app's pipeline must trigger an infrastructure or end-to-end test project.
By default the trigger job succeeds as soon as the downstream pipeline is created. With strategy: depend the trigger job waits and mirrors the downstream status, so a failing child fails the parent.
Dynamic child pipelines take this further: a job generates a YAML file (from a script, Jsonnet or a template) and saves it as an artifact; the trigger job includes it with include: - artifact: generated.yml, job: generate. This lets a pipeline create exactly the jobs needed, such as one per changed package.
Variables pass downstream via variables: in the trigger job (trigger:forward controls what is forwarded). Child pipelines appear nested in the parent's pipeline graph.
Example
generate:
stage: build
script:
- ./ci/make-jobs.sh > child.yml # writes one job per changed package
artifacts: {paths: [child.yml]}
run-generated:
stage: test
trigger:
include:
- artifact: child.yml
job: generate
strategy: depend # parent fails if child fails
backend:
trigger:
include: services/backend/.gitlab-ci.yml
strategy: depend
rules:
- changes: ["services/backend/**/*"]
e2e:
stage: deploy
variables: {APP_VERSION: $CI_COMMIT_SHORT_SHA}
trigger:
project: acme/e2e-tests
branch: mainRemember
- trigger:include starts a child pipeline; trigger:project another project's
- strategy: depend makes the trigger job mirror the downstream result
- Dynamic child pipelines include YAML generated by an earlier job
Watch out for
- Forgetting strategy: depend and getting a green parent while the child fails.