Keyword reference for the .gitlab-ci.yml file
all tiers

This document lists the configuration options for your GitLab .gitlab-ci.yml file.

When you are editing your .gitlab-ci.yml file, you can validate it with the CI Lint tool.

If you are editing this page, make sure you follow the CI/CD YAML reference style guide.

Keywords

A GitLab CI/CD pipeline configuration includes:

  • Global keywords that configure pipeline behavior:

    Keyword Description
    default Custom default values for job keywords.
    include Import configuration from other YAML files.
    stages The names and order of the pipeline stages.
    variables Define CI/CD variables for all job in the pipeline.
    workflow Control what types of pipeline run.

  • Jobs configured with job keywords:

    Keyword Description
    after_script Override a set of commands that are executed after job.
    allow_failure Allow job to fail. A failed job does not cause the pipeline to fail.
    artifacts List of files and directories to attach to a job on success.
    before_script Override a set of commands that are executed before job.
    cache List of files that should be cached between subsequent runs.
    coverage Code coverage settings for a given job.
    dast_configuration Use configuration from DAST profiles on a job level.
    dependencies Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from.
    environment Name of an environment to which the job deploys.
    except Control when jobs are not created.
    extends Configuration entries that this job inherits from.
    image Use Docker images.
    inherit Select which global defaults all jobs inherit.
    interruptible Defines if a job can be canceled when made redundant by a newer run.
    needs Execute jobs earlier than the stage ordering.
    only Control when jobs are created.
    pages Upload the result of a job to use with GitLab Pages.
    parallel How many instances of a job should be run in parallel.
    release Instructs the runner to generate a release object.
    resource_group Limit job concurrency.
    retry When and how many times a job can be auto-retried in case of a failure.
    rules List of conditions to evaluate and determine selected attributes of a job, and whether or not it’s created.
    script Shell script that is executed by a runner.
    secrets The CI/CD secrets the job needs.
    services Use Docker services images.
    stage Defines a job stage.
    tags List of tags that are used to select a runner.
    timeout Define a custom job-level timeout that takes precedence over the project-wide setting.
    trigger Defines a downstream pipeline trigger.
    variables Define job variables on a job level.
    when When to run job.

Global keywords

Some keywords are not defined in a job. These keywords control pipeline behavior or import additional pipeline configuration.

default

You can set global defaults for some keywords. Jobs that do not define one or more of the listed keywords use the value defined in the default section.

Keyword type: Global keyword.

Possible inputs: These keywords can have custom defaults:

Example of default: 

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: ruby:2.7
  script: bundle exec rspec

In this example, ruby:3.0 is the default image value for all jobs in the pipeline. The rspec 2.7 job does not use the default, because it overrides the default with a job-specific image section:

Additional details:

  • When the pipeline is created, each default is copied to all jobs that don’t have that keyword defined.
  • If a job already has one of the keywords configured, the configuration in the job takes precedence and is not replaced by the default.
  • Control inheritance of default keywords in jobs with inherit:default.

include

Use include to include external YAML files in your CI/CD configuration. You can split one long .gitlab-ci.yml file into multiple files to increase readability, or reduce duplication of the same configuration in multiple places.

You can also store template files in a central repository and include them in projects.

The include files are:

You can nest up to 100 includes. In , the same file can be included multiple times in nested includes, but duplicates are ignored.

In , the time limit to resolve all files is 30 seconds.

Keyword type: Global keyword.

Possible inputs: The include subkeys:

Additional details:

  • Use merging to customize and override included CI/CD configurations with local
  • You can override included configuration by having the same job name or global keyword in the .gitlab-ci.yml file. The two configurations are merged together, and the configuration in the .gitlab-ci.yml file takes precedence over the included configuration.

Related topics:

include:local

Use include:local to include a file that is in the same repository as the .gitlab-ci.yml file. Use include:local instead of symbolic links.

Keyword type: Global keyword.

Possible inputs:

Example of include:local: 

include:
  - local: '/templates/.gitlab-ci-template.yml'

You can also use shorter syntax to define the path: 

include: '.gitlab-ci-production.yml'

Additional details:

  • The .gitlab-ci.yml file and the local file must be on the same branch.
  • You can’t include local files through Git submodules paths.
  • All nested includes are executed in the scope of the same project, so you can use local, project, remote, or template includes.

include:file

Including multiple files from the same project

To include files from another private project on the same GitLab instance, use include:file. You can use include:file in combination with include:project only.

Keyword type: Global keyword.

Possible inputs:

Example of include:file: 

include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'

You can also specify a ref. If you do not specify a value, the ref defaults to the HEAD of the project: 

include:
  - project: 'my-group/my-project'
    ref: main
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: v1.0.0
    file: '/templates/.gitlab-ci-template.yml'

  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b  # Git SHA
    file: '/templates/.gitlab-ci-template.yml'

You can include multiple files from the same project: 

include:
  - project: 'my-group/my-project'
    ref: main
    file:
      - '/templates/.builds.yml'
      - '/templates/.tests.yml'

Additional details:

  • All nested includes are executed in the scope of the target project. You can use local (relative to the target project), project, remote, or template includes.
  • When the pipeline starts, the .gitlab-ci.yml file configuration included by all methods is evaluated. The configuration is a snapshot in time and persists in the database. GitLab does not reflect any changes to the referenced .gitlab-ci.yml file configuration until the next pipeline starts.
  • When you include a YAML file from another private project, the user running the pipeline must be a member of both projects and have the appropriate permissions to run pipelines. A not found or access denied error may be displayed if the user does not have access to any of the included files.

include:remote

Use include:remote with a full URL to include a file from a different location.

Keyword type: Global keyword.

Possible inputs:

  • A public URL accessible by an HTTP/HTTPS GET request. Authentication with the remote URL is not supported. The YAML file must have the extension .yml or .yaml.

Example of include:remote: 

include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'

Additional details:

  • All nested includes execute without context as a public user, so you can only include public projects or templates.
  • Be careful when including a remote CI/CD configuration file. No pipelines or notifications trigger when external CI/CD configuration files change. From a security perspective, this is similar to pulling a third-party dependency.

include:template

Use include:template to include .

Keyword type: Global keyword.

Possible inputs:

Example of include:template: 

# File sourced from the GitLab template collection
include:
  - template: Auto-DevOps.gitlab-ci.yml

Multiple include:template files: 

include:
  - template: Android-Fastlane.gitlab-ci.yml
  - template: Auto-DevOps.gitlab-ci.yml

Additional details:

  • All nested includes are executed only with the permission of the user, so it’s possible to use project, remote, or template includes.

stages

Use stages to define stages that contain groups of jobs. Use stage in a job to configure the job to run in a specific stage.

If stages is not defined in the .gitlab-ci.yml file, the default pipeline stages are:

The order of the items in stages defines the execution order for jobs:

  • Jobs in the same stage run in parallel.
  • Jobs in the next stage run after the jobs from the previous stage complete successfully.

Keyword type: Global keyword.

Example of stages: 

stages:
  - build
  - test
  - deploy

In this example:

  1. All jobs in build execute in parallel.
  2. If all jobs in build succeed, the test jobs execute in parallel.
  3. If all jobs in test succeed, the deploy jobs execute in parallel.
  4. If all jobs in deploy succeed, the pipeline is marked as passed.

If any job fails, the pipeline is marked as failed and jobs in later stages do not start. Jobs in the current stage are not stopped and continue to run.

Additional details:

  • If a job does not specify a stage, the job is assigned the test stage.
  • If a stage is defined but no jobs use it, the stage is not visible in the pipeline, which can help compliance pipeline configurations:
    • Stages can be defined in the compliance configuration but remain hidden if not used.
    • The defined stages become visible when developers use them in job definitions.

Related topics:

  • To make a job start earlier and ignore the stage order, use the needs keyword.

workflow

Use workflow to control pipeline behavior.

Related topics:

workflow:rules

The rules keyword in workflow is similar to rules defined in jobs, but controls whether or not a whole pipeline is created.

When no rules evaluate to true, the pipeline does not run.

Possible inputs: You can use some of the same keywords as job-level rules:

Example of workflow:rules: 

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

In this example, pipelines run if the commit title (first line of the commit message) does not end with -draft and the pipeline is for either:

  • A merge request
  • The default branch.

Additional details:

  • If your rules match both branch pipelines (other than the default branch) and merge request pipelines, duplicate pipelines can occur.

Related topics:

workflow:rules:variables

Version history

You can use variables in workflow:rules to define variables for specific pipeline conditions.

When the condition matches, the variable is created and can be used by all jobs in the pipeline. If the variable is already defined at the global level, the workflow variable takes precedence and overrides the global variable.

Keyword type: Global keyword.

Possible inputs: Variable name and value pairs:

  • The name can use only numbers, letters, and underscores (_).
  • The value must be a string.

Example of workflow:rules:variables: 

variables:
  DEPLOY_VARIABLE: "default-deploy"

workflow:
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:
        DEPLOY_VARIABLE: "deploy-production"  # Override globally-defined DEPLOY_VARIABLE
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Define a new variable.
    - when: always                            # Run the pipeline in other cases

job1:
  variables:
    DEPLOY_VARIABLE: "job1-default-deploy"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:                                   # Override DEPLOY_VARIABLE defined
        DEPLOY_VARIABLE: "job1-deploy-production"  # at the job level.
    - when: on_success                             # Run the job in other cases
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

job2:
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

When the branch is the default branch:

  • job1’s DEPLOY_VARIABLE is job1-deploy-production.
  • job2’s DEPLOY_VARIABLE is deploy-production.

When the branch is feature:

  • job1’s DEPLOY_VARIABLE is job1-default-deploy, and IS_A_FEATURE is true.
  • job2’s DEPLOY_VARIABLE is default-deploy, and IS_A_FEATURE is true.

When the branch is something else:

  • job1’s DEPLOY_VARIABLE is job1-default-deploy.
  • job2’s DEPLOY_VARIABLE is default-deploy.

Job keywords

The following topics explain how to use keywords to configure CI/CD pipelines.

after_script

Use after_script to define an array of commands that run after each job, including failed jobs.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs: An array including:

Example of after_script: 

job:
  script:
    - echo "An example script section."
  after_script:
    - echo "Execute this command after the `script` section completes."

Additional details:

Scripts you specify in after_script execute in a new shell, separate from any before_script or script commands. As a result, they:

If a job times out or is cancelled, the after_script commands do not execute. Related topics:

allow_failure

Use allow_failure to determine whether a pipeline should continue running when a job fails.

  • To let the pipeline continue running subsequent jobs, use allow_failure: true.
  • To stop the pipeline from running subsequent jobs, use allow_failure: false.

When jobs are allowed to fail (allow_failure: true) an orange warning () indicates that a job failed. However, the pipeline is successful and the associated commit is marked as passed with no warnings.

This same warning is displayed when:

  • All other jobs in the stage are successful.
  • All other jobs in the pipeline are successful.

The default value for allow_failure is:

  • true for manual jobs.
  • false for manual jobs that also use rules.
  • false in all other cases.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs:

  • true or false.

Example of allow_failure: 

job1:
  stage: test
  script:
    - execute_script_1

job2:
  stage: test
  script:
    - execute_script_2
  allow_failure: true

job3:
  stage: deploy
  script:
    - deploy_to_staging

In this example, job1 and job2 run in parallel:

  • If job1 fails, jobs in the deploy stage do not start.
  • If job2 fails, jobs in the deploy stage can still start.

Additional details:

  • You can use allow_failure as a subkey of rules.
  • You can use allow_failure: false with a manual job to create a blocking manual job. A blocked pipeline does not run any jobs in later stages until the manual job is started and completes successfully.

allow_failure:exit_codes

Version history

Use allow_failure:exit_codes to control when a job should be allowed to fail. The job is allow_failure: true for any of the listed exit codes, and allow_failure false for any other exit code.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs:

  • A single exit code.
  • An array of exit codes.

Example of allow_failure: 

test_job_1:
  script:
    - echo "Run a script that results in exit code 1. This job fails."
    - exit 1
  allow_failure:
    exit_codes: 137

test_job_2:
  script:
    - echo "Run a script that results in exit code 137. This job is allowed to fail."
    - exit 137
  allow_failure:
    exit_codes:
      - 137
      - 255

artifacts

Use artifacts to specify which files to save as job artifacts. Job artifacts are a list of files and directories that are attached to the job when it succeeds, fails, or always.

The artifacts are sent to GitLab after the job finishes. They are available for download in the GitLab UI if the size is smaller than the the maximum artifact size.

By default, jobs in later stages automatically download all the artifacts created by jobs in earlier stages. You can control artifact download behavior in jobs with dependencies.

When using the needs keyword, jobs can only download artifacts from the jobs defined in the needs configuration.

Job artifacts are only collected for successful jobs by default, and artifacts are restored after caches.

Read more about artifacts.

artifacts:exclude

Version history

Use artifacts:exclude to prevent files from being added to an artifacts archive.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • An array of file paths, relative to the project directory.
  • You can use Wildcards that use doublestar.PathMatch patterns.

Example of artifacts:exclude: 

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/**/*.o

This example stores all files in binaries/, but not *.o files located in subdirectories of binaries/.

Additional details:

  • artifacts:exclude paths are not searched recursively.
  • Files matched by artifacts:untracked can be excluded using artifacts:exclude too.

Related topics:

artifacts:expire_in

Version history

Use expire_in to specify how long job artifacts are stored before they expire and are deleted. The expire_in setting does not affect:

After their expiry, artifacts are deleted hourly by default (using a cron job), and are not accessible anymore.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs: The expiry time. If no unit is provided, the time is in seconds. Valid values include:

  • '42'
  • 42 seconds
  • 3 mins 4 sec
  • 2 hrs 20 min
  • 2h20min
  • 6 mos 1 day
  • 47 yrs 6 mos and 4d
  • 3 weeks and 2 days
  • never

Example of artifacts:expire_in: 

job:
  artifacts:
    expire_in: 1 week

Additional details:

  • The expiration time period begins when the artifact is uploaded and stored on GitLab. If the expiry time is not defined, it defaults to the instance wide setting.
  • To override the expiration date and protect artifacts from being automatically deleted:

artifacts:expose_as

Use the artifacts:expose_as keyword to expose job artifacts in the merge request UI.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • The name to display in the merge request UI for the artifacts download link. Must be combined with artifacts:paths.

Example of artifacts:expose_as: 

test:
  script: ["echo 'test' > file.txt"]
  artifacts:
    expose_as: 'artifact 1'
    paths: ['file.txt']

Additional details:

  • If artifacts:paths uses CI/CD variables, the artifacts do not display in the UI.
  • A maximum of 10 job artifacts per merge request can be exposed.
  • Glob patterns are unsupported.
  • If a directory is specified and there is more than one file in the directory, the link is to the job artifacts browser.
  • If GitLab Pages is enabled, GitLab automatically renders the artifacts when the artifacts is a single file with one of these extensions:
    • .html or .htm
    • .txt
    • .json
    • .xml
    • .log

Related topics:

artifacts:name

Use the artifacts:name keyword to define the name of the created artifacts archive. You can specify a unique name for every archive.

If not defined, the default name is artifacts, which becomes artifacts.zip when downloaded.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

Example of artifacts:name:

To create an archive with a name of the current job: 

job:
  artifacts:
    name: "job1-artifacts-file"
    paths:
      - binaries/

Related topics:

artifacts:paths

Paths are relative to the project directory ($CI_PROJECT_DIR) and can’t directly link outside it.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

Example of artifacts:paths: 

job:
  artifacts:
    paths:
      - binaries/
      - .config

This example creates an artifact with .config and all the files in the binaries directory.

Additional details:

  • If not used with artifacts:name defined, the artifacts file is named artifacts, which becomes artifacts.zip when downloaded.

Related topics:

artifacts:public

Version history
On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to enable the feature flag named non_public_artifacts. On GitLab.com, this feature is not available.

Use artifacts:public to determine whether the job artifacts should be publicly available.

When artifacts:public is true (default), the artifacts in public pipelines are available for download by anonymous and guest users.

To deny read access for anonymous and guest users to artifacts in public pipelines, set artifacts:public to false:

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • true (default if not defined) or false.

Example of artifacts:paths: 

job:
  artifacts:
    public: false

artifacts:reports

Use artifacts:reports to collect artifacts generated by included templates in jobs.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

Example of artifacts:reports: 

rspec:
  stage: test
  script:
    - bundle install
    - rspec --format RspecJunitFormatter --out rspec.xml
  artifacts:
    reports:
      junit: rspec.xml

Additional details:

artifacts:untracked

Use artifacts:untracked to add all Git untracked files as artifacts (along with the paths defined in artifacts:paths). artifacts:untracked ignores configuration in the repository’s .gitignore, so matching artifacts in .gitignore are included.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • true or false (default if not defined).

Example of artifacts:untracked:

Save all Git untracked files: 

job:
  artifacts:
    untracked: true

Related topics:

artifacts:when

Use artifacts:when to upload artifacts on job failure or despite the failure.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • on_success (default): Upload artifacts only when the job succeeds.
  • on_failure: Upload artifacts only when the job fails.
  • always: Always upload artifacts (except when jobs time out). For example, when uploading artifacts required to troubleshoot failing tests.

Example of artifacts:when: 

job:
  artifacts:
    when: on_failure

before_script

Use before_script to define an array of commands that should run before each job’s script commands, but after artifacts are restored.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs: An array including:

Example of before_script: 

job:
  before_script:
    - echo "Execute this command before any 'script:' commands."
  script:
    - echo "This command executes after the job's 'before_script' commands."

Additional details:

  • Scripts you specify in before_script are concatenated with any scripts you specify in the main script. The combined scripts execute together in a single shell.

Related topics:

cache

Use cache to specify a list of files and directories to cache between jobs. You can only use paths that are in the local working copy.

Caching is shared between pipelines and jobs. Caches are restored before artifacts.

Learn more about caches in Caching in GitLab CI/CD.

cache:paths

Use the cache:paths keyword to choose which files or directories to cache.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

Example of cache:paths:

Cache all files in binaries that end in .apk and the .config file: 

rspec:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache
    paths:
      - binaries/*.apk
      - .config

Related topics:

cache:key

Use the cache:key keyword to give each cache a unique identifying key. All jobs that use the same cache key use the same cache, including in different pipelines.

If not set, the default key is default. All jobs with the cache keyword but no cache:key share the default cache.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

Example of cache:key: 

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache-$CI_COMMIT_REF_SLUG
    paths:
      - binaries/

Additional details:

  • If you use Windows Batch to run your shell scripts you must replace $ with %. For example: key: %CI_COMMIT_REF_SLUG%

  • The cache:key value can’t contain:

    • The / character, or the equivalent URI-encoded %2F.
    • Only the . character (any number), or the equivalent URI-encoded %2E.
  • The cache is shared between jobs, so if you’re using different paths for different jobs, you should also set a different cache:key. Otherwise cache content can be overwritten.

Related topics:

cache:key:files

Use the cache:key:files keyword to generate a new key when one or two specific files change. cache:key:files lets you reuse some caches, and rebuild them less often, which speeds up subsequent pipeline runs.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • An array of one or two file paths.

Example of cache:key:files: 

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key:
      files:
        - Gemfile.lock
        - package.json
    paths:
      - vendor/ruby
      - node_modules

This example creates a cache for Ruby and Node.js dependencies. The cache is tied to the current versions of the Gemfile.lock and package.json files. When one of these files changes, a new cache key is computed and a new cache is created. Any future job runs that use the same Gemfile.lock and package.json with cache:key:files use the new cache, instead of rebuilding the dependencies.

Additional details:

  • The cache key is a SHA computed from the most recent commits that changed each listed file. If neither file is changed in any commits, the fallback key is default.
cache:key:prefix

Use cache:key:prefix to combine a prefix with the SHA computed for cache:key:files.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

Example of cache:key:prefix: 

rspec:
  script:
    - echo "This rspec job uses a cache."
  cache:
    key:
      files:
        - Gemfile.lock
      prefix: $CI_JOB_NAME
    paths:
      - vendor/ruby

For example, adding a prefix of $CI_JOB_NAME causes the key to look like rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5. If a branch changes Gemfile.lock, that branch has a new SHA checksum for cache:key:files. A new cache key is generated, and a new cache is created for that key. If Gemfile.lock is not found, the prefix is added to default, so the key in the example would be rspec-default.

Additional details:

  • If no file in cache:key:files is changed in any commits, the prefix is added to the default key.

cache:untracked

Use untracked: true to cache all files that are untracked in your Git repository:

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • true or false (default).

Example of cache:untracked: 

rspec:
  script: test
  cache:
    untracked: true

Additional details:

  • You can combine cache:untracked with cache:paths to cache all untracked files as well as files in the configured paths. For example: 

    rspec:
  script: test
  cache:
    untracked: true
    paths:
      - binaries/

cache:when

Use cache:when to define when to save the cache, based on the status of the job.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • on_success (default): Save the cache only when the job succeeds.
  • on_failure: Save the cache only when the job fails.
  • always: Always save the cache.

Example of cache:when: 

rspec:
  script: rspec
  cache:
    paths:
      - rspec/
    when: 'always'

This example stores the cache whether or not the job fails or succeeds.

cache:policy

To change the upload and download behavior of a cache, use the cache:policy keyword. By default, the job downloads the cache when the job starts, and uploads changes to the cache when the job ends. This caching style is the pull-push policy (default).

To set a job to only download the cache when the job starts, but never upload changes when the job finishes, use cache:policy:pull.

To set a job to only upload a cache when the job finishes, but never download the cache when the job starts, use cache:policy:push.

Use the pull policy when you have many jobs executing in parallel that use the same cache. This policy speeds up job execution and reduces load on the cache server. You can use a job with the push policy to build the cache.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • pull
  • push
  • pull-push (default)

Example of cache:policy: 

prepare-dependencies-job:
  stage: build
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: push
  script:
    - echo "This job only downloads dependencies and builds the cache."
    - echo "Downloading dependencies..."

faster-test-job:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - echo "This job script uses the cache, but does not update it."
    - echo "Running tests..."

coverage

Use coverage with a custom regular expression to configure how code coverage is extracted from the job output. The coverage is shown in the UI if at least one line in the job output matches the regular expression.

To extract the code coverage value from the match, GitLab uses this smaller regular expression: \d+(\.\d+)?.

Possible inputs:

  • A regular expression. Must start and end with /. Must match the coverage number. May match surrounding text as well, so you don’t need to use a regular expression character group to capture the exact number.

Example of coverage: 

job1:
  script: rspec
  coverage: '/Code coverage: \d+\.\d+/'

In this example:

  1. GitLab checks the job log for a match with the regular expression. A line like Code coverage: 67.89% of lines covered would match.
  2. GitLab then checks the matched fragment to find a match to \d+(\.\d+)?. The sample matching line above gives a code coverage of 67.89.

Additional details:

  • Coverage regular expressions set in gitlab-ci.yml take precedence over coverage regular expression set in the GitLab UI.
  • If there is more than one matched line in the job output, the last line is used (the first result of reverse search).
  • If there are multiple matches in a single line, the last match is searched for the coverage number.
  • If there are multiple coverage numbers found in the matched fragment, the first number is used.
  • Leading zeros are removed.
  • Coverage output from child pipelines is not recorded or displayed. Check for more details.

dast_configuration note

Use the dast_configuration keyword to specify a site profile and scanner profile to be used in a CI/CD configuration. Both profiles must first have been created in the project. The job’s stage must be dast.

Keyword type: Job keyword. You can use only as part of a job.

Possible inputs: One each of site_profile and scanner_profile.

Example of dast_configuration: 

stages:
  - build
  - dast

include:
  - template: DAST.gitlab-ci.yml

dast:
  dast_configuration:
    site_profile: "Example Co"
    scanner_profile: "Quick Passive Test"

In this example, the dast job extends the dast configuration added with the include keyword to select a specific site profile and scanner profile.

Additional details:

  • Settings contained in either a site profile or scanner profile take precedence over those contained in the DAST template.

Related topics:

dependencies

Use the dependencies keyword to define a list of jobs to fetch artifacts from. You can also set a job to download no artifacts at all.

If you do not use dependencies, all artifacts from previous stages are passed to each job.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs:

  • The names of jobs to fetch artifacts from.
  • An empty array ([]), to configure the job to not download any artifacts.

Example of dependencies: 

build osx:
  stage: build
  script: make build:osx
  artifacts:
    paths:
      - binaries/

build linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
      - binaries/

test osx:
  stage: test
  script: make test:osx
  dependencies:
    - build osx

test linux:
  stage: test
  script: make test:linux
  dependencies:
    - build linux

deploy:
  stage: deploy
  script: make deploy

In this example, two jobs have artifacts: build osx and build linux. When test osx is executed, the artifacts from build osx are downloaded and extracted in the context of the build. The same thing happens for test linux and artifacts from build linux.

The deploy job downloads artifacts from all previous jobs because of the stage precedence.

Additional details:

  • The job status does not matter. If a job fails or it’s a manual job that isn’t triggered, no error occurs.
  • If the artifacts of a dependent job are expired or deleted, then the job fails.

environment

Use environment to define the environment that a job deploys to.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs: The name of the environment the job deploys to, in one of these formats:

  • Plain text, including letters, digits, spaces, and these characters: -, _, /, $, {, }.
  • CI/CD variables, including predefined, project, group, instance, or variables defined in the .gitlab-ci.yml file. You can’t use variables defined in a script section.

Example of environment: 

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment: production

Additional details:

  • If you specify an environment and no environment with that name exists, an environment is created.

environment:name

Set a name for an environment.

Common environment names are qa, staging, and production, but you can use any name.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs: The name of the environment the job deploys to, in one of these formats:

  • Plain text, including letters, digits, spaces, and these characters: -, _, /, $, {, }.
  • CI/CD variables, including predefined, project, group, instance, or variables defined in the .gitlab-ci.yml file. You can’t use variables defined in a script section.

Example of environment:name: 

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production

environment:url

Set a URL for an environment.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs: A single URL, in one of these formats:

  • Plain text, like https://prod.example.com.
  • CI/CD variables, including predefined, project, group, instance, or variables defined in the .gitlab-ci.yml file. You can’t use variables defined in a script section.

Example of environment:url: 

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production
    url: https://prod.example.com

Additional details:

  • After the job completes, you can access the URL by selecting a button in the merge request, environment, or deployment pages.

environment:on_stop

Closing (stopping) environments can be achieved with the on_stop keyword defined under environment. It declares a different job that runs to close the environment.

Keyword type: Job keyword. You can use it only as part of a job.

Additional details:

environment:action

Use the action keyword to specify jobs that prepare, start, or stop environments.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs: One of the following keywords:

Value Description
start Default value. Indicates that the job starts the environment. The deployment is created after the job starts.
prepare Indicates that the job is only preparing the environment. It does not trigger deployments. Read more about preparing environments.
stop Indicates that the job stops a deployment. For more detail, read Stop an environment.

Example of environment:action: 

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

environment:auto_stop_in

The auto_stop_in keyword specifies the lifetime of the environment. When an environment expires, GitLab automatically stops it.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs: A period of time written in natural language. For example, these are all equivalent:

Example of environment:auto_stop_in: 

review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    auto_stop_in: 1 day

When the environment for review_app is created, the environment’s lifetime is set to 1 day. Every time the review app is deployed, that lifetime is also reset to 1 day.

Related topics:

environment:kubernetes

Use the kubernetes keyword to configure deployments to a Kubernetes cluster that is associated with your project.

Keyword type: Job keyword. You can use it only as part of a job.

Example of environment:kubernetes: 

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      namespace: production

This configuration sets up the deploy job to deploy to the production environment, using the production .

Additional details:

Related topics:

environment:deployment_tier

Use the deployment_tier keyword to specify the tier of the deployment environment.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs: One of the following:

Example of environment:deployment_tier: 

deploy:
  script: echo
  environment:
    name: customer-portal
    deployment_tier: production

Related topics:

Dynamic environments

Use CI/CD variables to dynamically name environments.

For example: 

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

The deploy as review app job is marked as a deployment to dynamically create the review/$CI_COMMIT_REF_SLUG environment. $CI_COMMIT_REF_SLUG is a CI/CD variable set by the runner. The $CI_ENVIRONMENT_SLUG variable is based on the environment name, but suitable for inclusion in URLs. If the deploy as review app job runs in a branch named pow, this environment would be accessible with a URL like https://review-pow.example.com/.

The common use case is to create dynamic environments for branches and use them as Review Apps. You can see an example that uses Review Apps at https://gitlab.com/gitlab-examples/review-apps-nginx/.

extends

Use extends to reuse configuration sections. It’s an alternative to YAML anchors and is a little more flexible and readable.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs:

  • The name of another job in the pipeline.
  • A list (array) of names of other jobs in the pipeline.

Example of extends: 

.tests:
  script: rake test
  stage: test
  only:
    refs:
      - branches

rspec:
  extends: .tests
  script: rake rspec
  only:
    variables:
      - $RSPEC

In this example, the rspec job uses the configuration from the .tests template job. When creating the pipeline, GitLab:

  • Performs a reverse deep merge based on the keys.
  • Merges the .tests content with the rspec job.
  • Doesn’t merge the values of the keys.

The result is this rspec job: 

rspec:
  script: rake rspec
  stage: test
  only:
    refs:
      - branches
    variables:
      - $RSPEC

Additional details:

  • In GitLab 12.0 and later, you can use multiple parents for extends.
  • The extends keyword supports up to eleven levels of inheritance, but you should avoid using more than three levels.
  • In the example above, .tests is a hidden job, but you can extend configuration from regular jobs as well.

Related topics:

image

Use image to specify a Docker image that the job runs in.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs: The name of the image, including the registry path if needed, in one of these formats:

  • <image-name> (Same as using <image-name> with the latest tag)
  • <image-name>:<tag>
  • <image-name>@<digest>

Example of image: 

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: registry.example.com/my-group/my-project/ruby:2.7
  script: bundle exec rspec

In this example, the ruby:3.0 image is the default for all jobs in the pipeline. The rspec 2.7 job does not use the default, because it overrides the default with a job-specific image section.

Related topics:

image:name

The name of the Docker image that the job runs in. Similar to image used by itself.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs: The name of the image, including the registry path if needed, in one of these formats:

  • <image-name> (Same as using <image-name> with the latest tag)
  • <image-name>:<tag>
  • <image-name>@<digest>

Example of image:name: 

image:
  name: "registry.example.com/my/image:latest"

Related topics:

image:entrypoint

Command or script to execute as the container’s entry point.

When the Docker container is created, the entrypoint is translated to the Docker --entrypoint option. The syntax is similar to the , where each shell token is a separate string in the array.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • A string.

Example of image:entrypoint: 

image:
  name: super/sql:experimental
  entrypoint: [""]

Related topics:

inherit

Use inherit to control inheritance of default keywords and variables.

inherit:default

Use inherit:default to control the inheritance of default keywords.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs:

  • true (default) or false to enable or disable the inheritance of all default keywords.
  • A list of specific default keywords to inherit.

Example of inherit:default: 

default:
  retry: 2
  image: ruby:3.0
  interruptible: true

job1:
  script: echo "This job does not inherit any default keywords."
  inherit:
    default: false

job2:
  script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'."
  inherit:
    default:
      - retry
      - image

Additional details:

  • You can also list default keywords to inherit on one line: default: [keyword1, keyword2]

inherit:variables

Use inherit:variables to control the inheritance of global variables keywords.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs:

  • true (default) or false to enable or disable the inheritance of all global variables.
  • A list of specific variables to inherit.

Example of inherit:variables: 

variables:
  VARIABLE1: "This is variable 1"
  VARIABLE2: "This is variable 2"
  VARIABLE3: "This is variable 3"

job1:
  script: echo "This job does not inherit any global variables."
  inherit:
    variables: false

job2:
  script: echo "This job inherits only the two listed global variables. It does not inherit 'VARIABLE3'."
  inherit:
    variables:
      - VARIABLE1
      - VARIABLE2

Additional details:

  • You can also list global variables to inherit on one line: variables: [VARIABLE1, VARIABLE2]

interruptible

Use interruptible if a job should be canceled when a newer pipeline starts before the job completes.

This keyword is used with the automatic cancellation of redundant pipelines feature. When enabled, a running job with interruptible: true can be cancelled when a new pipeline starts on the same branch.

You can’t cancel subsequent jobs after a job with interruptible: false starts.

Keyword type: Job keyword. You can use it only as part of a job or in the default section.

Possible inputs:

  • true or false (default).

Example of interruptible: 

stages:
  - stage1
  - stage2
  - stage3

step-1:
  stage: stage1
  script:
    - echo "Can be canceled."
  interruptible: true

step-2:
  stage: stage2
  script:
    - echo "Can not be canceled."

step-3:
  stage: stage3
  script:
    - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible."
  interruptible: true

In this example, a new pipeline causes a running pipeline to be:

  • Canceled, if only step-1 is running or pending.
  • Not canceled, after step-2 starts.

Additional details:

  • Only set interruptible: true if the job can be safely canceled after it has started, like a build job. Deployment jobs usually shouldn’t be cancelled, to prevent partial deployments.
  • To completely cancel a running pipeline, all jobs must have interruptible: true, or interruptible: false jobs must not have started.

needs

Version history

Use needs to execute jobs out-of-order. Relationships between jobs that use needs can be visualized as a directed acyclic graph.

You can ignore stage ordering and run some jobs without waiting for others to complete. Jobs in multiple stages can run concurrently.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs:

  • An array of jobs.
  • An empty array ([]), to set the job to start as soon as the pipeline is created.

Example of needs: 

linux:build:
  stage: build
  script: echo "Building linux..."

mac:build:
  stage: build
  script: echo "Building mac..."

lint:
  stage: test
  needs: []
  script: echo "Linting..."

linux:rspec:
  stage: test
  needs: ["linux:build"]
  script: echo "Running rspec on linux..."

mac:rspec:
  stage: test
  needs: ["mac:build"]
  script: echo "Running rspec on mac..."

production:
  stage: deploy
  script: echo "Running production..."

This example creates four paths of execution:

  • Linter: The lint job runs immediately without waiting for the build stage to complete because it has no needs (needs: []).
  • Linux path: The linux:rspec job runs as soon as the linux:build job finishes, without waiting for mac:build to finish.
  • macOS path: The mac:rspec jobs runs as soon as the mac:build job finishes, without waiting for linux:build to finish.
  • The production job runs as soon as all previous jobs finish: linux:build, linux:rspec, mac:build, mac:rspec.

Additional details:

needs:artifacts

When a job uses needs, it no longer downloads all artifacts from previous stages by default, because jobs with needs can start before earlier stages complete. With needs you can only download artifacts from the jobs listed in the needs configuration.

Use artifacts: true (default) or artifacts: false to control when artifacts are downloaded in jobs that use needs.

Keyword type: Job keyword. You can use it only as part of a job. Must be used with needs:job.

Possible inputs:

Example of needs:artifacts: 

test-job1:
  stage: test
  needs:
    - job: build_job1
      artifacts: true

test-job2:
  stage: test
  needs:
    - job: build_job2
      artifacts: false

test-job3:
  needs:
    - job: build_job1
      artifacts: true
    - job: build_job2
    - build_job3

In this example:

  • The test-job1 job downloads the build_job1 artifacts
  • The test-job2 job does not download the build_job2 artifacts.
  • The test-job3 job downloads the artifacts from all three build_jobs, because artifacts is true, or defaults to true, for all three needed jobs.

Additional details:

needs:project
premium

Use needs:project to download artifacts from up to five jobs in other pipelines. The artifacts are downloaded from the latest successful pipeline for the specified ref.

If there is a pipeline running for the specified ref, a job with needs:project does not wait for the pipeline to complete. Instead, the job downloads the artifact from the latest pipeline that completed successfully.

needs:project must be used with job, ref, and artifacts.

Keyword type: Job keyword. You can use it only as part of a job.

Possible inputs:

Examples of needs:project: 

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: namespace/group/project-name
      job: build-1
      ref: main
      artifacts: true

In this example, build_job downloads the artifacts from the latest successful build-1 job on the main branch in the group/project-name project.

In GitLab 13.3 and later, you can use CI/CD variables in needs:project, for example: 

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: $CI_PROJECT_PATH
      job: $DEPENDENCY_JOB_NAME
      ref: $ARTIFACTS_DOWNLOAD_REF
      artifacts: true

Additional details: