Gitlab CI

GitLab CI Multi-Project Pipelines

Overview

Orchestrate CI/CD pipelines across multiple GitLab projects using trigger jobs, cross-pipeline dependencies, and pipeline subscriptions. Covers patterns from simple downstream triggers to complex tag cascade orchestration.

Trigger Mechanism Decision Tree

Need cross-project pipeline orchestration?
├── One repo triggers another's pipeline
│   ├── Fire-and-forget → trigger: (default)
│   └── Wait for completion → trigger: + strategy: depend
├── Repo B depends on Repo A's artifacts
│   └── needs: project: + job: + ref: + artifacts: true
├── Orchestrate multiple repos in sequence
│   └── Orchestrator pattern: parent triggers children via stages
├── Auto-trigger on upstream completion
│   └── Pipeline subscriptions (Settings > CI/CD)
└── Tag/release cascade across repos
    └── Orchestrator with strategy: depend per stage

Core Patterns

1. Downstream Trigger (Fire-and-Forget)

trigger_downstream:
  stage: deploy
  trigger:
    project: my-group/downstream-project
    branch: main

2. Synchronous Trigger (Wait for Completion)

trigger_downstream:
  stage: deploy
  trigger:
    project: my-group/downstream-project
    branch: main
    strategy: depend  # Parent job status mirrors downstream result

3. Cross-Project Artifact Dependency

# In downstream project - fetch artifacts from upstream
consume_artifacts:
  stage: test
  script: cat artifact.txt
  needs:
    - project: my-group/upstream-project
      job: build_artifacts
      ref: main
      artifacts: true

4. Conditional Triggers

trigger_on_tag:
  stage: deploy
  trigger:
    project: my-group/downstream-project
  rules:
    - if: $CI_COMMIT_TAG

5. Passing Variables Downstream

trigger_with_vars:
  stage: deploy
  variables:
    UPSTREAM_VERSION: $CI_COMMIT_TAG
    UPSTREAM_REF: $CI_COMMIT_SHA
  trigger:
    project: my-group/downstream-project

Key Constraints

• Max 1000 downstream pipelines per hierarchy
• Parent-child pipelines: max depth of 2 levels
• Triggering user needs Developer access in downstream project
• needs: project: requires GitLab 15.9+ and job token scope allowlist
• Cannot use CI/CD variables in include: sections
• Pipeline subscriptions: max 2 per project (self-managed configurable)
• Pipeline subscriptions only trigger on tag pipeline completion

References

Detailed patterns, templates, and architecture-specific configurations:

• Multi-Project Trigger Reference — all trigger mechanisms, variable passing, artifact sharing, pipeline subscriptions
• Cross-Pipeline Gating Patterns — orchestrator pattern, sequential stage triggers, tag cascade, scheduled rebuilds
• Edge Infrastructure Templates — ready-to-use templates for multi-repo Nix flake architecture with builder/os/k3s-core/services

External Docs

• GitLab Downstream Pipelines
• Pipeline Architecture
• CI/CD Pipelines

Source: kettleofketchup/KettleOfSkills — distributed by TomeVault.