Why We Transitioned to Downstream Pipelines in GitLab

CI/CD Pipeline Refactor: From Monolith to Downstream

Overview

We’ve refactored our CI/CD setup to adopt downstream pipelines, replacing the monolithic structure we previously had. This change improves clarity, speed, reliability, and scalability across all environments (sandbox, UAT, production).

---

Before: Monolithic Pipeline

Issues with the Old Setup:

• All jobs lived in one pipeline — tightly coupled build, deploy, security, test jobs

• Deploys were tightly linked to builds — you couldn’t deploy without rebuilding

• Cluttered UI — all environments were visible even when not relevant

• Hard to debug or retry — a failed job often meant restarting everything Scaling was painful — adding new environments or services bloated the pipeline

---

After: Modular Downstream Pipelines

Parent Pipeline (main pipeline)
├── build_job (build + artifact)
└── trigger_deploy_pipeline (child, strategy: depend)
      ├── deploy_sandbox
      ├── deploy_uat
      └── deploy_prod

Benefits of the New Setup:

• Separation of concerns — build and deploy logic are decoupled

• Artifact reuse — deploy pipelines consume artifacts from the build job

• Re-run deploys — re-run only the deploy pipeline without triggering a new build

• Environment isolation — deploys are environment-specific and scoped

• Better UI — each pipeline shows only the jobs relevant to its stage

More Info on Downstream Pipelines: https://docs.gitlab.com/ci/pipelines/downstream_pipelines/

Sample Layout

---

Developer-Focused Comparison

---

What You Can Do Now

• Trigger deploys manually or from MR merges

• Recreate downstream pipelines to redeploy without rebuilding

• Extend pipeline logic easily using includes and shared templates

• Debug more cleanly — failures are isolated to one stage or environment

• Releases automatically build for sprint releases, hotfix's, offcycle's

---

Summary

This new structure reflects how we build software: modular, testable, maintainable. It enables us to move faster, deploy safer, and scale CI/CD with our growth.