Configuring GitLab CI/CD to Trigger Cross‑Project Pipelines

Why Validate Code with Related Components?

A typical example is a micro‑service architecture where each service lives in its own repository and pipeline; developers must ensure their changes do not break dependent services, requiring tests across those services.

Cross‑Project Pipelines

When running a project pipeline, you may also want to trigger pipelines in other projects that will deploy and test the latest versions of related micro‑services. GitLab CI/CD offers a simple way to trigger other pipelines as part of your CI by adding a trigger job.

GitLab CI/CD Configuration File

In each project, the .gitlab-ci.yml file defines the pipeline, its jobs, stages, and the GitLab Runner that executes them. This file is version‑controlled and editable with any IDE.

Adding a Cross‑Project Pipeline Trigger Job

Since GitLab 11.8, a new syntax allows you to define a bridge job that triggers a downstream pipeline. Example configuration:

//job1 is a job in the upstream project
deploy:
  stage: Deploy
  script: this is my script

//job2 is a bridge job in the upstream project which triggers cross‑project pipeline
Android:
  stage: Trigger-cross-projects
  trigger: mobile/android

When the deploy job succeeds, the Android job is created in a pending state and triggers a downstream pipeline in the mobile/android project.

Viewing Downstream Pipelines from the Upstream Graph

GitLab CI/CD provides visual pipeline graphs. After a successful deploy job, four other projects are triggered, and you can click a downstream job to navigate to its pipeline.

The downstream pipeline can be scrolled into view, and you can switch between upstream and downstream pipelines.

Specifying the Downstream Pipeline Branch

You can define which branch the downstream pipeline should use:

trigger:
  project: mobile/android
  branch: stable-11-2

The project keyword gives the full path of the downstream project, and branch selects the branch whose HEAD commit will be used.

Passing Variables to the Downstream Pipeline

Variables can be passed to the downstream pipeline using the variables keyword, just like in regular jobs:

Android:
  variables:
    ENVIRONMENT: 'This is the variable value for the downstream pipeline'
  stage: Trigger-cross-projects
  trigger: mobile/android

The ENVIRONMENT variable becomes available to every job in the downstream pipeline as an environment variable.

The .gitlab-ci.yml file defines the order of CI/CD stages, the jobs to run, and the conditions for execution. By adding a bridge job with the trigger keyword, you can launch downstream pipelines, pass parameters, and even specify the branch to use.

Complex pipelines may contain many sequential and parallel jobs, and they can trigger downstream pipelines. GitLab provides pipeline graphs to visualize the flow and status of both upstream and downstream pipelines.