GitLab CI/CD is the continuous integration and continuous delivery system built into GitLab, which runs automated pipelines of build, test, security and deployment jobs every time code changes. Pipelines are defined as code in a `.gitlab-ci.yml` file stored in the repository, and the jobs are executed by separate agents called GitLab Runners.
In DevOps practice, GitLab CI/CD is valued because it places source control, pipelines, merge requests, container registry and environments in one platform. Teams use it to enforce quality gates before merging, to produce versioned artifacts and to promote releases through staging and production with a full audit trail.
How GitLab CI/CD pipelines are structured
A pipeline is the top-level unit of execution, created by an event such as a push, a merge request, a tag, a schedule or an API call. It consists of stages that run in sequence and jobs that run in parallel within a stage. If any required job fails, later stages do not start by default, which makes the pipeline a fail-fast quality gate.
Every job declares a script, an execution image or environment, and optional rules that decide whether it runs. Jobs pass files to later jobs as artifacts and reuse dependencies between runs through a cache. The needs keyword turns the stage sequence into a directed acyclic graph, so a job can start as soon as its specific dependencies finish rather than waiting for the whole previous stage.
| Element | Purpose | Defined by |
|---|---|---|
| Pipeline | One run triggered by an event | Push, merge request, schedule, API |
| Stage | Ordered group of jobs | stages keyword |
| Job | Unit of work with a script | Top-level key in the YAML file |
| Artifact | Files handed to later jobs or downloaded | artifacts keyword |
| Cache | Reused dependencies between pipelines | cache keyword |
| Environment | Deployment target with history | environment keyword |
GitLab runners and executors
A GitLab Runner is the agent that polls the GitLab instance for pending jobs, executes them and reports logs and status back. The server only orchestrates; all build work happens on runners. Runners can be shared across an instance, assigned to a group or dedicated to one project, and tags route jobs to runners with specific capabilities such as GPUs or ARM processors.
The executor determines how a runner isolates each job. The choice affects security, speed and reproducibility, and it is one of the most consequential infrastructure decisions in a GitLab CI/CD setup.
| Executor | Isolation | Strength | Typical risk |
|---|---|---|---|
| Shell | None beyond the host user | Simple, fast startup | Jobs can affect each other |
| Docker | Container per job | Reproducible images | Privileged mode weakens isolation |
| Kubernetes | Pod per job | Elastic cluster capacity | Requires cluster operations skills |
| Docker Autoscaler | Container on cloud VMs | Scales with demand | Cold-start delay for new VMs |
| Custom | Defined by the operator | Fits special hardware | Maintenance burden |
Hosted runners on GitLab.com bill by compute minutes, while self-managed runners cost only the underlying infrastructure. Organizations with sensitive code or private network targets usually run self-managed runners inside their own network, so that deployment credentials never leave controlled systems.
Pipeline types and advanced features
Beyond the basic branch pipeline, GitLab CI/CD offers several pipeline types for different workflows. Merge request pipelines test proposed changes, while merged results pipelines test the change combined with the current target branch, catching integration breakage that isolated branch tests miss. Merge trains queue several merge requests and validate each in sequence to keep the main branch green.
Large codebases use parent-child pipelines to split configuration per component and multi-project pipelines to trigger downstream repositories. The include keyword and CI/CD components let platform teams publish reusable, versioned templates, which reduces duplication across hundreds of projects.
| Pipeline type | Triggered by | Use it when |
|---|---|---|
| Branch pipeline | Push to a branch | Simple projects and release branches |
| Merge request pipeline | Opening or updating a merge request | Testing proposed changes only |
| Merged results pipeline | Merge request with simulated merge | Main branch changes frequently |
| Merge train | Queue of approved merge requests | Many contributors merge daily |
| Parent-child pipeline | Trigger job in the same project | Monorepos with many components |
| Scheduled pipeline | Cron-style schedule | Nightly builds and dependency scans |
How GitLab CI/CD compares with other CI tools
GitLab CI/CD, GitHub Actions and Jenkins solve the same problem with different architectural assumptions. GitLab favors an integrated platform with built-in security scanning and environments; GitHub Actions favors a marketplace of reusable actions; Jenkins favors maximal flexibility through plugins and self-hosting.
| Aspect | GitLab CI/CD | GitHub Actions | Jenkins |
|---|---|---|---|
| Configuration | .gitlab-ci.yml in the repository | Workflow files under .github/workflows | Jenkinsfile or UI jobs |
| Reuse model | Includes and CI/CD components | Marketplace actions | Plugins and shared libraries |
| Hosting | SaaS or self-managed | SaaS with self-hosted runners | Self-hosted |
| Built-in security scans | SAST, DAST, dependency scanning | Code scanning add-ons | Through plugins |
| Operational effort | Low to moderate | Low | High |
GitLab also supports GitOps-style delivery through its agent for Kubernetes, where a cluster pulls desired state from a repository instead of receiving pushed deployments. Many teams combine both: pipelines build and test images, and a GitOps controller applies them to clusters.
Common mistakes and good practices
Most GitLab CI/CD problems come from slow, insecure or duplicated configuration rather than from the platform itself. Experienced teams treat pipeline code with the same review discipline as application code.
- Unprotected secrets: store credentials as masked, protected CI/CD variables or in an external vault, never in the YAML file.
- Overuse of privileged Docker-in-Docker: prefer rootless image builders where possible, because privileged containers can reach the host.
- Missing cache keys: without a key tied to the lock file, caches grow stale or are never reused.
- Sequential stages everywhere: use
needsto run independent jobs early and shorten feedback time. - Copied YAML across projects: move shared logic into versioned components so fixes reach every pipeline.
A useful target is feedback within about ten minutes for merge request pipelines. Slow pipelines push developers toward larger, riskier changes, which works against the short lead times that DevOps and DORA metrics reward.
Explained without jargon
Think of GitLab CI/CD as an automatic assembly line for software. A developer saves a change. The line picks it up, builds the program and runs a series of checks. If everything passes, it delivers the result to users. No one has to repeat these steps by hand, and a broken change is stopped before it reaches customers.
The instructions live in a small text file next to the code. So the process is written down and reviewed like the software itself.
A typical use case
A team of twelve developers maintains a payment service written in Go. Their .gitlab-ci.yml defines four stages: build, test, scan and deploy. Merge request pipelines compile the code, run about 1,400 unit tests in three parallel jobs and execute dependency and static security scans on self-managed runners using the Kubernetes executor. A cache keyed to the module lock file cuts dependency downloads from two minutes to fifteen seconds.
After a merge to the main branch, the pipeline builds a container image, pushes it to the project registry and deploys it automatically to a staging environment. Promotion to production is a manual job protected by approval rules. With this setup, the team reduced average merge request feedback from 25 to 8 minutes and now ships several small releases per day, each traceable to the exact commit and pipeline that produced it.