← Full reference

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

KeyWhat it sets
stageslist of stages in order; default build, test, deploy (plus the special .pre and .post)
variablesvariables for all jobs
defaultdefaults for all jobs: image, before_script, after_script, cache, retry, tags…
includeinclude other YAML files
workflow: rules:whether to run the pipeline at all

Job keys

What to run and where

KeyWhat it sets
stagethe job's stage (default test)
scriptshell commands — a required key (unless there's trigger or extends)
before_script / after_scriptcommands before / after script (after_script runs even on failure)
imagethe Docker image the job runs in
servicesextra side containers (a DB and so on), with alias — the host name
variablesjob variables
tagspick a runner by tags
extendsinherit keys from a template (a hidden job)
timeout / retrytime limit / how many times to retry on failure
parallel: matrix:run the job several times with different sets of variables
triggerstart a child pipeline or another project's pipeline

When to run

KeyWhat it sets
ruleslist 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
whenon_success (default), manual (button), always, on_failure, delayed (+ start_in), never
allow_failurea failed job doesn't fail the pipeline
only / exceptthe deprecated way to set conditions (branches, tags, variables); can't be combined with rules in one job

Dependencies and files

KeyWhat it sets
needsstart right after the given jobs without waiting for the stage to finish; needs: [] — immediately
dependencieswhich jobs' artifacts to download ([] — none)
artifacts: paths:files saved after the job and passed on to later ones
artifacts: expire_in / when / reportsretention period / on which outcome to save / reports (junit and others)
cache: key: paths:cache between runs (dependencies), not guaranteed
environmentdeployment environment: name, url
resource_groupdon't run two jobs with the same group in parallel
coveragea regular expression to extract the coverage percentage from the log

include variants

NotationFrom where
- local: path/file.ymlfrom the same repository
- project: group/project + file: + ref:from another GitLab project
- remote: https://…/file.ymlby URL
- template: name.gitlab-ci.ymla built-in GitLab template

Predefined variables

VariableValue
CI_COMMIT_BRANCHbranch (empty for tags and merge requests)
CI_DEFAULT_BRANCHthe project's default branch
CI_COMMIT_TAGtag, if the pipeline runs for a tag
CI_COMMIT_SHA / CI_COMMIT_SHORT_SHAcommit hash
CI_PIPELINE_SOURCEwhy it was started: push, merge_request_event, schedule, web…
CI_PROJECT_DIRdirectory with the sources inside the job
CI_JOB_NAME, CI_PIPELINE_IDjob name, pipeline number
CI_REGISTRY_IMAGEaddress 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 script won't run: GitLab rejects the whole file.
  • stage must be in stages. A typo in a stage name is a configuration error. A job without stage goes to test.
  • 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.
  • rules and only/except can't be used in the same job, GitLab rejects the configuration. The local yamlschema check doesn't catch this.
  • If no rules entry matches, the job isn't added to the pipeline. A rule without if at the end works as an "else".
  • needs refers 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_script runs in a separate shell: variables and cd from script aren't visible there.
  • Tags like !reference [.template, script] are understood by GitLab but not by a regular YAML parser: yamlschema reports a parse error on them.

See also

github-actions · git · yq · docker-compose