Using GitLab CI/CD to Trigger Cross‑Project Pipelines

Continuous Integration (CI) automatically builds and tests code before merging into the master branch, allowing developers to catch errors early and reduce the risk of introducing new bugs into the main repository.

After CI, deploying and testing in a real environment is essential; moving from CI to Continuous Delivery/Deployment (CD) is the next step in a mature DevOps workflow, enabling integrated testing of a project’s code with other components and services.

Why validate code against related components?

In microservice architectures, each service often lives in its own repository and pipeline. Different teams manage different services, so developers must ensure their changes do not break dependent microservices, requiring tests to be run on those services as well.

Cross‑project pipelines

When a project pipeline runs, you may want to trigger pipelines in other projects that deploy and test the latest versions of related microservices. GitLab CI/CD offers a simple, flexible way to trigger such downstream pipelines by adding a trigger job to the CI configuration.

GitLab CI/CD configuration file

The .gitlab-ci.yml file in each project defines the pipeline, its jobs, stages, and the GitLab Runner that executes them. It is version‑controlled, editable with any IDE, and allows developers to modify pipeline behavior without involving system administrators.

Adding a cross‑project pipeline trigger job

Since GitLab 11.8, a new syntax enables triggering downstream pipelines. The example below shows a bridge job that triggers a downstream pipeline in the mobile/android project after the deploy job succeeds.

//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 finishes successfully, the Android job is created in a pending state; GitLab then creates a downstream pipeline in the mobile/android project, and the job succeeds once that pipeline is ready. The user who creates the upstream pipeline must have access to the downstream project; otherwise the job fails.

From upstream pipeline graph to downstream

GitLab CI/CD provides visual pipeline graphs. After the deploy stage succeeds, four other projects are triggered in parallel, and you can click any downstream job to navigate to its pipeline.

Specifying the downstream pipeline branch

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

The project keyword gives the full path of the downstream project, and branch selects which branch the downstream pipeline should use, based on the current HEAD commit of that branch.

Passing variables to the downstream pipeline

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

The ENVIRONMENT variable is passed to every job in the downstream pipeline and becomes an environment variable for the GitLab Runner.

The .gitlab-ci.yml file also defines the order of CI/CD stages, which jobs to run, and under what conditions they are executed. Adding a bridge job with the trigger keyword allows you to pass parameters, choose a branch, and orchestrate complex pipelines that include both sequential and parallel jobs.

GitLab also offers a pipeline graph view to help understand the flow of both upstream and downstream pipelines.

Related resources

The article includes links to many other GitLab CI/CD tutorials, such as pipeline triggering methods, runner registration, and GitOps practices with Argo CD.