Skip to main content
Mapagam

Using Multi-Project Pipelines

1. Triggering Multi-Project Pipelines

Multi-project pipelines in GitLab allow you to trigger pipelines across multiple projects from a single pipeline. This is useful for orchestrating complex workflows that span several repositories.

Trigger Type Description Configuration
Project-level trigger Triggers a pipeline in another project using a token. trigger: with project and token
Pipeline-level trigger Triggers a pipeline in another project using a pipeline token. trigger: with project and pipeline

Example: Triggering a Pipeline in Another Project

trigger_pipeline:
  trigger:
    project: "group/subgroup/project-name"
    token: $PIPELINE_TRIGGER_TOKEN
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
Note: The token must be a valid pipeline trigger token configured in the target project.
Warning: Ensure that the pipeline trigger token has appropriate permissions to execute the target pipeline.

2. Using Downstream Pipelines

Property Description Example
trigger Triggers a downstream pipeline in another project trigger:
project Specifies the downstream project to trigger project: group/subgroup/project
pipeline Specifies the downstream pipeline to trigger pipeline: main
strategy Strategy for triggering downstream pipelines strategy: depend

Example: Triggering a Downstream Pipeline

trigger_downstream:
  trigger:
    project: "group/subgroup/downstream-project"
    pipeline: "main"
Note: The downstream pipeline will inherit the variables from the upstream pipeline.
Warning: Ensure that the downstream project has proper access to the upstream pipeline's variables.

Key Points

  • Downstream pipelines can be triggered from an upstream pipeline.
  • The trigger keyword is used to define the downstream project and pipeline.
  • Variables are inherited from the upstream pipeline to the downstream pipeline.

3. Passing Artifacts Between Projects

Property Description Values
artifacts.project Specifies the project path to fetch artifacts from namespace/project-name
artifacts.job Name of the job in the source project that produces artifacts build
artifacts.path Path to the artifact files in the source project build/

Example: Fetching artifacts from another project

job_in_target_project:
  trigger:
    project: "namespace/other-project"
    job: "build"
  artifacts:
    paths:
      - build/
Note: The target project must have the build job configured to produce artifacts.
Warning: Ensure that the project has proper permissions to access artifacts from another project.

4. Setting Project Permissions

Permission Level Description Access to Multi-Project Pipelines Notes
Guest Read-only access to project resources DEPRECATED in favor of Reporter Cannot trigger or modify pipelines
Reporter Read access to project resources and pipeline history Can view pipeline status and logs Can trigger pipelines if allowed by project settings
Developer Full access to project resources and pipelines Can trigger, modify, and manage pipelines Default permission for pipeline triggers in multi-project setups
Maintainer Full access to project resources and pipelines, including settings Can manage pipeline schedules, variables, and settings Can configure project-level permissions for multi-project pipelines
Owner Full access to project resources and pipelines, including project deletion Can manage all aspects of multi-project pipeline configuration Can grant permissions to other users and groups

Example: Setting Pipeline Permissions via API

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --request PUT \
     "https://gitlab.example.com/api/v4/projects/<project_id>/pipeline_permissions" \
     --data "{"
Note: Multi-project pipeline permissions are inherited from the project's member roles. Ensure that users have appropriate access levels in each project to execute pipelines.
Warning: Setting overly permissive permissions can lead to unauthorized pipeline execution or modification. Always follow the principle of least privilege.

5. Using Cross-Project Dependencies

GitLab CI/CD allows you to define dependencies between pipelines in different projects using the trigger keyword. This enables multi-project pipeline workflows where one project's pipeline can trigger another project's pipeline.

Property Description Values
trigger Defines a cross-project pipeline trigger project, pipeline
project Specifies the target project path (e.g., group/project) string
pipeline Specifies the target pipeline (e.g., main) string
ref Branch, tag, or commit to use for the triggered pipeline string
variables Variables to pass to the triggered pipeline map

Example: Triggering a Pipeline in Another Project

trigger_pipeline:
  trigger:
    project: "group/subproject"
    ref: "main"
    variables:
      ENVIRONMENT: "staging"
Note: The trigger keyword requires appropriate permissions to access the target project and pipeline.
Warning: Cross-project triggers can lead to infinite loops if not configured carefully. Ensure that pipelines do not recursively trigger each other.

Key Points

  • Use trigger to initiate pipelines in other projects.
  • Supports passing variables to the triggered pipeline.
  • Requires proper project access and permissions.

6. Implementing Microservice Pipelines

Microservice pipelines in GitLab CI/CD allow you to manage and deploy multiple microservices within a single project or across multiple projects. These pipelines can be orchestrated using GitLab's multi-project pipeline features.

Feature Description Usage
multi-project pipelines Allows triggering and managing pipelines across multiple projects. Use trigger keyword in a pipeline to start another project's pipeline.
pipeline triggers Triggers a pipeline in another project using a token or API. Use trigger with project and token.
pipeline variables Passes variables between pipelines in different projects. Use variables in the trigger block.

Example: Triggering a Pipeline in Another Project

deploy:
  trigger:
    project: "my-org/microservice-deploy"
    branch: "main"
    token: $DEPLOY_TOKEN

Example: Passing Variables to a Multi-Project Pipeline

build:
  trigger:
    project: "my-org/microservice-deploy"
    variables:
      ENVIRONMENT: "staging"
      VERSION: "v1.2.3"
Note: Ensure that the DEPLOY_TOKEN is properly configured in your GitLab project's CI/CD settings.

Key Points

  • Multi-project pipelines enable orchestration of microservices across projects.
  • Pipelines can be triggered using the trigger keyword in a job.
  • Variables can be passed between pipelines to maintain context and state.

7. Using needs:project Configuration

The needs:project configuration in GitLab CI/CD allows a job to depend on artifacts or pipeline results from another project. This is useful for multi-project pipelines where jobs in one project need data or outputs from another project.

Property Description Values Notes
needs:project Specifies the project from which to fetch artifacts or pipeline results. path/to/project Must be a valid project path in the format namespace/project.
needs:job Name of the job in the target project that provides artifacts or pipeline results. job_name Optional, defaults to the last successful job if not specified.
needs:ref Branch, tag, or commit SHA from which to fetch artifacts. main, v1.0, abc123 Defaults to the default branch of the project.
needs:artifacts Whether to fetch artifacts from the target project. true, false Defaults to true.

Example: Using needs:project to fetch artifacts from another project

job_a:
  needs:
    - project: "group1/project1"
      job: "build_artifacts"
      ref: "main"
  script:
    - echo "Using artifacts from project1"
Note: The project specified in needs:project must be accessible to the current project, and the user or service account running the pipeline must have permission to access it.
Warning: If the target project's pipeline fails or does not produce artifacts, the job that depends on it will also fail.

8. Tracking Multi-Project Status

Property Description Values
pipeline.status Current status of the pipeline running, success, failed, canceled
pipeline.id Unique identifier for the pipeline 123456789
project.name Name of the project frontend-app
project.path_with_namespace Full path to the project group1/frontend-app

Example: Pipeline Status API Response

{
  "id": 123456789,
  "status": "success",
  "project": {
    "name": "frontend-app",
    "path_with_namespace": "group1/frontend-app"
  },
  "created_at": "2026-04-01T10:00:00Z"
}
Note: The status can be tracked via GitLab API or through the UI. For multi-project pipelines, each project's status is reported separately.

9. Debugging Multi-Project Pipelines

Example: Using debug job in multi-project pipeline

debug_job:
  stage: debug
  script:
    - echo "Debugging multi-project pipeline"
    - git fetch --all
    - git branch -a
  only:
    - branches
Property Description Notes
debug_job Job to run debug commands Use only: to limit scope
stage Execution stage for debug job Set to debug to isolate from other stages
Note: Debug jobs should not be part of the main pipeline execution flow.

Debugging Workflow

  1. Create a debug job in the .gitlab-ci.yml file
  2. Set stage: debug to isolate the job
  3. Add debugging commands like git fetch --all
  4. Use only: to control when the job runs

Debugging Tips

  • Use echo commands to print variable values
  • Run git status or ls -la to inspect the working directory
  • Use git log --oneline to check recent commits

10. Implementing Release Coordination

Feature Description Usage
release Defines a release in GitLab CI/CD release: block in a job
tag_name Name of the tag to create for the release tag_name: v1.0.0
name Release title name: Release v1.0.0
description Release notes or description description: Release notes for v1.0.0
assets.links Links to release assets assets.links: [{ name: 'artifact', url: '/path/to/artifact' }]

Example: Creating a Release

release_job:
  stage: release
  script:
    - echo "Creating release"
  release:
    tag_name: v1.0.0
    name: Release v1.0.0
    description: "Release notes for version 1.0.0"
    assets:
      links:
        - name: 'artifact'
          url: '/path/to/artifact'
Note: The release keyword is available in GitLab CI/CD starting from version 15.0.

Was this article helpful?

Related Cheat Sheets