GitLab CI

GitLab CI/CD is the pipeline system built into GitLab. Source code, merge requests, the container registry, security scanning and environments sit in one product, which reduces the integration work needed to get from commit to deployment.

How it works

Pipelines are described in a .gitlab-ci.yml file at the root of the repository. A pipeline is made of jobs, and each job belongs to a stage. If stages is not defined, the defaults are .pre, build, test, deploy and .post, and a job with no stage runs in test. Jobs in the same stage can run in parallel; stages run in order.

Jobs are executed by GitLab Runners, which can be shared runners provided by the GitLab instance or self-managed runners that you register yourself. Self-managed runners are common when jobs need access to private networks or specific hardware.

Several keywords shape how a pipeline behaves. rules decides whether a job is created, needs lets a job start before the whole previous stage has finished, cache keeps dependencies between jobs, and artifacts attaches build output to a job so later jobs can use it.

A practical example

stages: [build, test, deploy]

build-app:
  stage: build
  script: make build
  artifacts:
    paths: [binaries/]

test-app:
  stage: test
  script: make test

deploy-app:
  stage: deploy
  script: make deploy
  needs: [build-app]
  rules: [{if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'}]

Here the deploy job is only created on the default branch, and it can start as soon as the build job has finished.

Common mistakes

• Caching build output that should be an artifact, or the reverse. Caches are an optimisation and may be missing; artifacts are the supported way to pass files between jobs.
• Storing secrets in the YAML file instead of protected CI/CD variables or an external secrets manager.
• Leaving every job on every branch, so merge request pipelines run deployment logic. Use rules to scope jobs.
• Copying large blocks of YAML between projects rather than reusing shared templates with include.

When to use it and when not to

GitLab CI suits teams that already host code in GitLab and want review, pipelines and environments tracked together. It is less natural when source code lives elsewhere or when an organisation has standardised on another pipeline tool, in which case GitHub Actions or Jenkins may fit better. For the wider practice, see CI/CD and our CI/CD pipeline service.

See also

• CI/CD
• GitHub Actions
• Jenkins
• GitLab CI technology page