Multi-Project Pipelines
You'll learn how to trigger and coordinate GitLab pipelines across multiple projects for complex, multi-repository workflows.
What Are Multi-Project Pipelines?
Multi-project pipelines let you trigger a pipeline in another GitLab project from your current project's pipeline. Think of it as a "pipeline handoff" — when your API project finishes building, it can automatically kick off the integration-test project's pipeline, which might then trigger the deployment project's pipeline.
This differs from parent-child pipelines (which stay within one project). Multi-project pipelines connect separate repositories, each with their own .gitlab-ci.yml files.
Why Use Multi-Project Pipelines?
In microservices architectures or large systems, you often have:
- A library project that multiple services depend on
- A deployment orchestrator project that coordinates releases
- Downstream testing projects that validate integrations
When the library changes, you want to automatically test all dependent services. Multi-project pipelines make this coordination possible.
How It Works
You use the trigger keyword in a job to start a pipeline in another project:
trigger_downstream:
stage: deploy
trigger:
project: team/integration-tests
branch: main
This creates a downstream pipeline in the team/integration-tests project. You can pass variables, wait for completion, or fire-and-forget.
Analogy: It's like a relay race — your project finishes its leg and passes the baton to the next project's pipeline.
Bridge Jobs
The triggering job becomes a bridge job — it doesn't run scripts itself, it just connects pipelines. You can configure whether your pipeline waits for the downstream pipeline to complete or continues immediately.
Key Takeaway: Multi-project pipelines orchestrate workflows across repository boundaries by triggering pipelines in other GitLab projects, enabling coordinated builds, tests, and deployments in complex, multi-repo architectures.