Using GitLab CI/CD to Trigger Cross‑Project Pipelines for Microservices

Continuous Integration (CI) automatically builds and tests code before it is merged 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 the code in a real environment is important; moving from CI to Continuous Delivery/Deployment (CD) is the next step in DevOps maturity, enabling projects to test code together with other components and services.

Why validate code with related components?

A typical example is a micro‑services architecture where each service lives in its own repository and pipeline. Different teams manage different services, so developers must ensure their changes do not break dependent micro‑services, requiring tests to run on those services as well.

Cross‑Project Pipelines

When a project pipeline runs, you may want to trigger pipelines in other projects that will deploy and test the latest versions of all related micro‑services. GitLab CI/CD provides a simple, flexible way to trigger other pipelines by adding a trigger job to the CI configuration.

GitLab CI/CD Configuration File

In GitLab CI/CD, each project defines its pipeline, jobs, and stages in a .gitlab-ci.yml file that lives in the repository. The file is version‑controlled and can be edited with any IDE. It specifies the pipeline structure, the GitLab Runner that executes jobs, and the conditions under which jobs run or are skipped.

Add Cross‑Project Pipeline Trigger Job

Since GitLab 11.8, a new CI/CD syntax allows triggering downstream pipelines. The example below shows a bridge job that triggers a downstream pipeline:

//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 bridge job is created in a pending state. GitLab then creates a downstream pipeline in the mobile/android project; once the pipeline exists, the Android job succeeds.

The user who creates the upstream pipeline must have access to the downstream project; otherwise the bridge job fails.

Browse Downstream from Upstream Pipeline Graph

GitLab CI/CD visualizes pipeline configurations. In the diagram, the build, test, and deploy stages belong to the upstream project. After the deploy job succeeds, four other projects are triggered in parallel, and you can click a downstream job to navigate to its pipeline.

The second image shows the downstream pipeline; you can scroll left to view the upstream pipeline or right to return to the downstream one.

Specify 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 name. GitLab creates the downstream pipeline from the HEAD commit of that branch.

Pass Variables to Downstream Pipeline

To pass variables to a downstream pipeline, use 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. Adding a bridge job with the trigger keyword enables downstream pipelines, allows passing parameters, and can specify the branch to use.

Pipelines can become complex structures with many sequential and parallel jobs, and they may trigger downstream pipelines. GitLab provides a pipeline graph to view the flow and status of both upstream and downstream pipelines.

If this article helped you, feel free to share, like, and follow for more content.