GitLab CI/CD

On this page 7

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.

ElementPurposeDefined by
PipelineOne run triggered by an eventPush, merge request, schedule, API
StageOrdered group of jobsstages keyword
JobUnit of work with a scriptTop-level key in the YAML file
ArtifactFiles handed to later jobs or downloadedartifacts keyword
CacheReused dependencies between pipelinescache keyword
EnvironmentDeployment target with historyenvironment keyword
Core building blocks of a GitLab pipeline

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.

ExecutorIsolationStrengthTypical risk
ShellNone beyond the host userSimple, fast startupJobs can affect each other
DockerContainer per jobReproducible imagesPrivileged mode weakens isolation
KubernetesPod per jobElastic cluster capacityRequires cluster operations skills
Docker AutoscalerContainer on cloud VMsScales with demandCold-start delay for new VMs
CustomDefined by the operatorFits special hardwareMaintenance burden
Common runner executors compared

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 typeTriggered byUse it when
Branch pipelinePush to a branchSimple projects and release branches
Merge request pipelineOpening or updating a merge requestTesting proposed changes only
Merged results pipelineMerge request with simulated mergeMain branch changes frequently
Merge trainQueue of approved merge requestsMany contributors merge daily
Parent-child pipelineTrigger job in the same projectMonorepos with many components
Scheduled pipelineCron-style scheduleNightly builds and dependency scans
Pipeline types and when to use them

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.

AspectGitLab CI/CDGitHub ActionsJenkins
Configuration.gitlab-ci.yml in the repositoryWorkflow files under .github/workflowsJenkinsfile or UI jobs
Reuse modelIncludes and CI/CD componentsMarketplace actionsPlugins and shared libraries
HostingSaaS or self-managedSaaS with self-hosted runnersSelf-hosted
Built-in security scansSAST, DAST, dependency scanningCode scanning add-onsThrough plugins
Operational effortLow to moderateLowHigh
Comparison with neighboring CI/CD systems

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 needs to 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.