GitLab CI (.gitlab-ci.yml)
GitLab CI pipelines — stages, jobs, script, rules, needs, artifacts, cache, extends, include, variables
GitLab CI runs a pipeline from the .gitlab-ci.yml file at the repository root. A pipeline consists of jobs, and jobs are grouped into stages. Stages run one after another, jobs within a stage run in parallel. Each job runs its script commands on a runner, usually in a clean Docker container.
Checking in the sandbox: yamlschema gitlab-ci .gitlab-ci.yml validates the file against GitLab's official JSON schema and additionally checks that every job has a script and that its stage is declared.
Syntax
stages: # order of stages
- build
- test
job_name: # any top-level key except reserved ones is a job
stage: test
script:
- command
Keys starting with a dot (.template) are hidden: they aren't jobs but templates for extends.
Top-level keys
| Key | What it sets |
|---|---|
stages | list of stages in order; default build, test, deploy (plus the special .pre and .post) |
variables | variables for all jobs |
default | defaults for all jobs: image, before_script, after_script, cache, retry, tags… |
include | include other YAML files |
workflow: rules: | whether to run the pipeline at all |
Job keys
What to run and where
| Key | What it sets |
|---|---|
stage | the job's stage (default test) |
script | shell commands — a required key (unless there's trigger or extends) |
before_script / after_script | commands before / after script (after_script runs even on failure) |
image | the Docker image the job runs in |
services | extra side containers (a DB and so on), with alias — the host name |
variables | job variables |
tags | pick a runner by tags |
extends | inherit keys from a template (a hidden job) |
timeout / retry | time limit / how many times to retry on failure |
parallel: matrix: | run the job several times with different sets of variables |
trigger | start a child pipeline or another project's pipeline |
When to run
| Key | What it sets |
|---|---|
rules | list of conditions; the first matching one wins |
rules: - if: | an expression over variables: $CI_COMMIT_BRANCH == "main", $VAR =~ /^v\d+/ |
rules: - changes: | only if files matching the patterns changed |
rules: - exists: | only if the file exists in the repository |
when | on_success (default), manual (button), always, on_failure, delayed (+ start_in), never |
allow_failure | a failed job doesn't fail the pipeline |
only / except | the deprecated way to set conditions (branches, tags, variables); can't be combined with rules in one job |
Dependencies and files
| Key | What it sets |
|---|---|
needs | start right after the given jobs without waiting for the stage to finish; needs: [] — immediately |
dependencies | which jobs' artifacts to download ([] — none) |
artifacts: paths: | files saved after the job and passed on to later ones |
artifacts: expire_in / when / reports | retention period / on which outcome to save / reports (junit and others) |
cache: key: paths: | cache between runs (dependencies), not guaranteed |
environment | deployment environment: name, url |
resource_group | don't run two jobs with the same group in parallel |
coverage | a regular expression to extract the coverage percentage from the log |
include variants
| Notation | From where |
|---|---|
- local: path/file.yml | from the same repository |
- project: group/project + file: + ref: | from another GitLab project |
- remote: https://…/file.yml | by URL |
- template: name.gitlab-ci.yml | a built-in GitLab template |
Predefined variables
| Variable | Value |
|---|---|
CI_COMMIT_BRANCH | branch (empty for tags and merge requests) |
CI_DEFAULT_BRANCH | the project's default branch |
CI_COMMIT_TAG | tag, if the pipeline runs for a tag |
CI_COMMIT_SHA / CI_COMMIT_SHORT_SHA | commit hash |
CI_PIPELINE_SOURCE | why it was started: push, merge_request_event, schedule, web… |
CI_PROJECT_DIR | directory with the sources inside the job |
CI_JOB_NAME, CI_PIPELINE_ID | job name, pipeline number |
CI_REGISTRY_IMAGE | address of the project's images in the GitLab registry |
Examples
stages:
- build
- test
- deploy
variables:
APP_ENV: staging
default:
image: alpine:3.20
.base:
before_script:
- echo "common setup"
build:
stage: build
extends: .base
script:
- mkdir -p dist
- echo "built" > dist/app.txt
artifacts:
paths:
- dist/
expire_in: 1 week
unit:
stage: test
needs: [build]
script:
- cat dist/app.txt
lint:
stage: test
needs: []
script:
- echo lint
docs:
stage: test
script:
- echo "docs changed"
rules:
- changes:
- docs/**/*
deploy:
stage: deploy
script:
- echo "deploy to $APP_ENV"
environment: production
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
A pipeline only for the default branch, tags and merge requests:
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_TAG
# validate the file against the schema
yamlschema gitlab-ci .gitlab-ci.yml && echo OK
# typical messages:
# job: job has no script
# job: stage 'tests' is not declared in stages
# job: Additional properties are not allowed ('scripts' was unexpected)
# quickly see which jobs are in the file
yq 'keys' .gitlab-ci.yml
Pitfalls
- A job without
scriptwon't run: GitLab rejects the whole file. stagemust be instages. A typo in a stage name is a configuration error. A job withoutstagegoes totest.- A colon followed by a space inside a command breaks YAML. YAML reads
- echo "a: b"as the mapping{'echo "a': 'b"'}. Wrap the whole line in single quotes:- 'echo "a: b"'— or use a|block. rulesandonly/exceptcan't be used in the same job, GitLab rejects the configuration. The localyamlschemacheck doesn't catch this.- If no
rulesentry matches, the job isn't added to the pipeline. A rule withoutifat the end works as an "else". needsrefers to jobs by name, and they must exist in the pipeline. The schema doesn't check this — only GitLab itself reports the error.- Artifacts and cache are different things. Artifacts are guaranteed to be passed to jobs in later stages; the cache is just a speed-up and can't be relied on to pass results.
- Jobs don't share a filesystem. What one job creates shows up in another only via
artifacts. after_scriptruns in a separate shell: variables andcdfromscriptaren't visible there.- Tags like
!reference [.template, script]are understood by GitLab but not by a regular YAML parser:yamlschemareports a parse error on them.
See also
github-actions · git · yq · docker-compose