GitLab CI/CD
In plain English
Plain definition
GitLab CI/CD is the built-in automation system inside GitLab that runs your build, test and deployment steps automatically whenever code changes. You describe the steps once in a configuration file stored alongside your code, and GitLab CI/CD carries them out consistently every time.
How it works with stages, jobs and runners
A pipeline is defined declaratively in a YAML configuration file (conventionally .gitlab-ci.yml) stored in the project repository. The configuration defines stages and jobs; jobs within the same stage can run in parallel, while stages execute in sequence unless directed acyclic graph (DAG) relationships are explicitly defined using needs. Each job is executed by a runner, an agent process that GitLab dispatches work to, which may be instance-wide (formerly called shared), group-level or project-specific, and which executes jobs inside an isolated environment such as a container, shell or virtual machine, according to the configured executor.
Where you meet it in software delivery
GitLab CI/CD is used to automate the software delivery lifecycle: linting, unit and integration testing, artefact building, container image publishing, and deployment to target environments. It makes these steps repeatable, auditable and gated by defined rules (for example, running only on specific branches, tags or merge request events). Because pipeline configuration is version-controlled alongside application code, changes to the delivery process are reviewed and tracked using the same mechanisms as code changes, so change control and rollback cover the pipeline definition itself as well as the application.
Where it fits between GitLab and its runners
GitLab CI/CD sits between the GitLab repository and one or more execution environments. The GitLab instance (SaaS or self-managed) coordinates pipeline scheduling and job dispatch; runners, which may be hosted by GitLab, by the organisation, or by a third party, poll for or receive jobs and report status back. Runners commonly execute inside container orchestration platforms (such as Kubernetes) or dedicated virtual machines, and jobs frequently interact with external systems such as container registries, artifact stores, secret managers and target deployment platforms. So a pipeline only works when a runner is available, the executor is configured correctly, and every external system a job touches has correctly scoped credentials.
A two-stage example with a manual deploy
A minimal pipeline definition might declare two stages, test and deploy, where a test job runs the project’s automated test suite on every push, and a deploy job runs only on the default branch after the test stage succeeds. The deploy job is usually set to run manually, or under an explicit rule, so production never changes unattended.
stages:
- test
- deploy
run_tests:
stage: test
script:
- echo "Run the project test suite here"
deploy_production:
stage: deploy
script:
- echo "Run the deployment step here"
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
when: manual
Two misconceptions about runners and green pipelines
People often take a runner for a GitLab feature, but it is a separately deployed agent. Runner health, capacity and executor configuration are operational concerns distinct from the pipeline configuration itself, and a syntactically valid .gitlab-ci.yml will still fail to execute if no compatible runner is available or authorised for the project or group. The second mistake is treating a green pipeline as a successful deployment. A pipeline stage completing does not by itself confirm that a deployed change is healthy in the target environment, which is why separate validation and monitoring after deployment remain necessary.
Related GitLab CI/CD terms
- Runner
- Pipeline
- Stage and job
- Continuous integration
- Continuous delivery
- Merge request pipeline
Checks before you rely on a pipeline
Before a production-relevant workflow depends on a GitLab CI/CD pipeline, confirm the following in a non-production project or a protected branch with restricted merge permissions:
- Verify pipeline syntax without triggering job execution, using GitLab’s CI lint capability, and confirm the reported result is valid before merging configuration changes.
- Confirm that the intended runner is available, correctly tagged, and authorised for the project or group before assuming a pipeline will execute as designed.
- Review job-level access to secrets and deployment credentials to confirm least-privilege scope, since a runner executes with whatever access its environment and CI/CD variables grant it.
- If a pipeline change produces unexpected results, revert the specific commit to
.gitlab-ci.ymlthrough the normal Git workflow rather than editing pipeline state directly, since the configuration is the recoverable source of truth.
Give every deployment job its own rollback plan, separate from the pipeline. GitLab CI/CD automates the execution of steps you define, but it does not itself guarantee that a deployment can be safely reversed unless that reversal is explicitly built into the pipeline or into the target platform’s own recovery mechanism.
Related reading
Authoritative Sources
About this page
Was this useful?
Reports go to the site owner and are used to correct pages. Corrections are listed at /corrections.