CI/CD YAML syntax reference

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

This document lists the configuration options for the GitLab .gitlab-ci.yml file. This file is where you define the CI/CD jobs that make up your pipeline.

• If you are already familiar with basic CI/CD concepts, try creating your own .gitlab-ci.yml file by following a tutorial that demonstrates a simple or complex pipeline.
• For a collection of examples, see GitLab CI/CD examples.
• To view a large .gitlab-ci.yml file used in an enterprise, see the .gitlab-ci.yml file for gitlab.

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

GitLab CI/CD configuration uses YAML formatting, so the order of keywords is not important unless otherwise specified.

Use CI/CD expressions for more dynamic pipeline configuration options.

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 default CI/CD variables for all jobs in the pipeline.
  workflow	Control what types of pipeline run.

• Header keywords

  Keyword	Description
  spec	Define specifications for external configuration files.

• 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.
  extends	Configuration entries that this job inherits from.
  identity	Authenticate with third party services using identity federation.
  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.
  manual_confirmation	Define a custom confirmation message for a manual job.
  needs	Execute jobs earlier than the stage ordering.
  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.
  run	Run configuration that is executed by a runner.
  secrets	The CI/CD secrets the job needs.
  services	Use Docker services images.
  stage	Defines a job stage.
  start_in	Delay job execution for a specified duration. Requires when: delayed.
  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 CI/CD variables for individual jobs.
  when	When to run job.

• Deprecated keywords that are no longer recommended for use.

Global keywords

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

default

{{< history >}}

• Support for id_tokens introduced in GitLab 16.4.

{{< /history >}}

You can set global defaults for some keywords. Each default keyword is copied to every job that doesn't already have it defined.

Default configuration does not merge with job configuration. If the job already has a keyword defined, the job keyword takes precedence and the default configuration for that keyword is not used.

Keyword type: Global keyword.

Supported values: These keywords can have custom defaults:

• after_script
• artifacts
• before_script
• cache
• hooks
• id_tokens
• image
• interruptible
• retry
• services
• tags

Example of default:

default:
  image: ruby:3.0
  retry: 2

rspec:
  script: bundle exec rspec

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

In this example:

• image: ruby:3.0 and retry: 2 are the default keywords for all jobs in the pipeline.
• The rspec job does not have image or retry defined, so it uses the defaults of image: ruby:3.0 and retry: 2.
• The rspec 2.7 job does not have retry defined, but it does have image explicitly defined. It uses the default retry: 2, but ignores the default image and uses the image: ruby:2.7 defined in the job.

Additional details:

• Control inheritance of default keywords in jobs with inherit:default.
• Global defaults are not passed to downstream pipelines, which run independently of the upstream pipeline that triggered the downstream pipeline.

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:

• Merged with those in the .gitlab-ci.yml file.
• Always evaluated first and then merged with the content of the .gitlab-ci.yml file, regardless of the position of the include keyword.

The time limit to resolve all files is 30 seconds.

Keyword type: Global keyword.

Supported values: The include subkeys:

• include:component
• include:local
• include:project
• include:remote
• include:template

And optionally:

• include:inputs
• include:rules
• include:integrity
• include:cache

Additional details:

• Only certain CI/CD variables can be used with include keywords.
• 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.
• If you rerun a:
  • Job, the include files are not fetched again. All jobs in a pipeline use the configuration fetched when the pipeline was created. Any changes to the source include files do not affect job reruns.
  • Pipeline, the include files are fetched again. If they changed after the last pipeline run, the new pipeline uses the changed configuration.
• You can have up to 150 includes per pipeline by default, including nested. Additionally:
  • In GitLab 16.0 and later users on GitLab Self-Managed can change the maximum includes value.
  • In GitLab 15.10 and later you can have up to 150 includes. In nested includes, the same file can be included multiple times, but duplicated includes count towards the limit.
  • From GitLab 14.9 to GitLab 15.9, you can have up to 100 includes. The same file can be included multiple times in nested includes, but duplicates are ignored.

include:component

Use include:component to add a CI/CD component to the pipeline configuration.

Keyword type: Global keyword.

Supported values: The full address of the CI/CD component, formatted as <fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>.

Example of include:component:

include:
  - component: $CI_SERVER_FQDN/my-org/security-components/[email protected]

Related topics:

• Use a CI/CD component.

include:local

Use include:local to include a file that is in the same repository and branch as the configuration file containing the include keyword. Use include:local instead of symbolic links.

Keyword type: Global keyword.

Supported values:

A full path relative to the root directory (/):

• The YAML file must have the extension .yml or .yaml.
• You can use * and ** wildcards in the file path.
• You can use certain CI/CD variables.

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.
• include configuration is always evaluated based on the location of the file containing the include keyword, not the project running the pipeline. If a nested include is in a configuration file in a different project, include: local checks that other project for the file.

include:project

To include files from another private project on the same GitLab instance, use include:project and include:file.

Keyword type: Global keyword.

Supported values:

• include:project: The full GitLab project path.
• include:file A full file path, or array of file paths, relative to the root directory (/). The YAML files must have the .yml or .yaml extension.
• include:ref: Optional. The ref to retrieve the file from. Defaults to the HEAD of the project when not specified.
• You can use certain CI/CD variables.

Example of include:project:

include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-subgroup/my-project-2'
    file:
      - '/templates/.builds.yml'
      - '/templates/.tests.yml'

You can also specify a ref:

include:
  - project: 'my-group/my-project'
    ref: main                                      # Git branch
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: v1.0.0                                    # Git Tag
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b  # Git SHA
    file: '/templates/.gitlab-ci-template.yml'

Additional details:

• include configuration is always evaluated based on the location of the file containing the include keyword, not the project running the pipeline. If a nested include is in a configuration file in a different project, include: local checks that other project for the file.
• 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.
• Be careful when including another project's CI/CD configuration file. No pipelines or notifications trigger when CI/CD configuration files change. From a security perspective, this is similar to pulling a third-party dependency. For the ref, consider:
  • Using a specific SHA hash, which should be the most stable option. Use the full 40-character SHA hash to ensure the desired commit is referenced, because using a short SHA hash for the ref might be ambiguous.
  • Applying both protected branch and protected tag rules to the ref in the other project. Protected tags and branches are more likely to pass through change management before changing.

include:remote

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

Keyword type: Global keyword.

Supported values:

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.
• You can use certain CI/CD variables.

Example of include:remote:

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

Additional details:

• All nested includes are executed without context as a public user, so you can only include public projects or templates. No variables are available in the include section of nested includes.
• Be careful when including another project's CI/CD configuration file. No pipelines or notifications trigger when the other project's files change. From a security perspective, this is similar to pulling a third-party dependency. To verify the integrity of the included file, consider using the integrity keyword. If you link to another GitLab project you own, consider the use of both protected branches and protected tags to enforce change management rules.

include:template

Use include:template to include .gitlab-ci.yml templates.

Keyword type: Global keyword.

Supported values:

• The filename of a CI/CD template, for example Auto-DevOps.gitlab-ci.yml.
• You can use certain CI/CD variables.

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 templates can be viewed in lib/gitlab/ci/templates. Not all templates are designed to be used with include:template, so check template comments before using one.
• All nested includes are executed without context as a public user, so you can only include public projects or templates. No variables are available in the include section of nested includes.

include:inputs

{{< history >}}

• Introduced in GitLab 15.11 as a beta feature.
• Made generally available in GitLab 17.0.

{{< /history >}}

Use include:inputs to set the values for input parameters when the included configuration uses spec:inputs and is added to the pipeline.

Keyword type: Global keyword.

Supported values: A string, numeric value, or boolean.

Example of include:inputs:

include:
  - local: 'custom_configuration.yml'
    inputs:
      website: "My website"

In this example:

• The configuration contained in custom_configuration.yml is added to the pipeline, with a website input set to a value of My website for the included configuration.

Additional details:

• If the included configuration file uses spec:inputs:type, the input value must match the defined type.
• If the included configuration file uses spec:inputs:options, the input value must match one of the listed options.

Related topics:

• Set input values when using include.

include:rules

You can use rules with include to conditionally include other configuration files.

Keyword type: Global keyword.

Supported values: These rules subkeys:

• rules:if.
• rules:exists.
• rules:changes.

Some CI/CD variables are supported.

Example of include:rules:

include:
  - local: build_jobs.yml
    rules:
      - if: $INCLUDE_BUILDS == "true"

test-job:
  stage: test
  script: echo "This is a test job"

In this example, if the INCLUDE_BUILDS variable is:

• true, the build_jobs.yml configuration is included in the pipeline.
• Not true or does not exist, the build_jobs.yml configuration is not included in the pipeline.

Related topics:

• Examples of using include with:
  • rules:if.
  • rules:changes.
  • rules:exists.

include:integrity

{{< history >}}

• Introduced in GitLab 17.9.

{{< /history >}}

Use integrity with include:remote to specify a SHA256 hash of the included remote file. If integrity does not match the actual content, the remote file is not processed and the pipeline fails.

Keyword type: Global keyword.

Supported values: Base64-encoded SHA256 hash of the included content.

Example of include:integrity:

include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'
    integrity: 'sha256-L3/GAoKaw0Arw6hDCKeKQlV1QPEgHYxGBHsH4zG1IY8='

include:cache

{{< details >}}

• Status: Experiment

{{< /details >}}

{{< history >}}

• Introduced in GitLab 18.9 as an experiment with a feature flag named ci_cache_remote_includes. Disabled by default.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

Use cache with include:remote to cache the fetched remote file content and reduce HTTP requests. When enabled, the remote file is cached for a specified time-to-live (TTL), improving pipeline performance for configurations that use the same remote includes repeatedly.

Consider the trade-off between performance and freshness when setting cache durations. Longer cache durations improve performance but might use stale content if the remote file changes frequently.

When cache is not defined, the remote file is fetched every time.

Keyword type: Global keyword.

Supported values:

• true: Enable caching with a default time-to-live (TTL) of 1 hour.
• A duration (string): Valid TTL duration strings use time units like minutes, hours, or days (minimum 1 minute).

Example of include:cache:

include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/sample1.gitlab-ci.yml'
    cache: true
  - remote: 'https://gitlab.com/example-project/-/raw/main/sample2.gitlab-ci.yml'
    cache: '1 day'

Additional details:

• Caching is only available for include:remote.
• After the remote file is cached, the cached version continues to be used until the TTL expires, even if the remote file content changes.
• If you use integrity with cache, the integrity check is performed on every pipeline run, even when using cached content.

stages

{{< history >}}

• Support for nested array of strings introduced in GitLab 16.9.

{{< /history >}}

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:

• .pre
• build
• test
• deploy
• .post

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.

If a pipeline contains only jobs in the .pre or .post stages, it does not run. There must be at least one other job in a different stage.

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.

You can use some predefined CI/CD variables in workflow configuration, but not variables that are only defined when jobs start.

Related topics:

• workflow: rules examples
• Switch between branch pipelines and merge request pipelines

workflow:auto_cancel:on_new_commit

{{< history >}}

• Introduced in GitLab 16.8 with a flag named ci_workflow_auto_cancel_on_new_commit. Disabled by default.
• Enabled on GitLab.com and GitLab Self-Managed in GitLab 16.9.
• Generally available in GitLab 16.10. Feature flag ci_workflow_auto_cancel_on_new_commit removed.

{{< /history >}}

Use workflow:auto_cancel:on_new_commit to configure the behavior of the auto-cancel redundant pipelines feature.

Supported values:

• conservative: Cancel the pipeline, but only if no jobs with interruptible: false have started yet. Default when not defined.
• interruptible: Cancel only jobs with interruptible: true.
• none: Do not auto-cancel any jobs.

Example of workflow:auto_cancel:on_new_commit:

workflow:
  auto_cancel:
    on_new_commit: interruptible

job1:
  interruptible: true
  script: sleep 60

job2:
  interruptible: false  # Default when not defined.
  script: sleep 60

In this example:

• When a new commit is pushed to a branch, GitLab creates a new pipeline and job1 and job2 start.
• If a new commit is pushed to the branch before the jobs complete, only job1 is canceled.

workflow:auto_cancel:on_job_failure

{{< history >}}

• Introduced in GitLab 16.10 with a flag named auto_cancel_pipeline_on_job_failure. Disabled by default.
• Generally available in GitLab 16.11. Feature flag auto_cancel_pipeline_on_job_failure removed.

{{< /history >}}

Use workflow:auto_cancel:on_job_failure to configure which jobs should be canceled as soon as one job fails.

Supported values:

• all: Cancel the pipeline and all running jobs as soon as one job fails.
• none: Do not auto-cancel any jobs.

Example of workflow:auto_cancel:on_job_failure:

stages: [stage_a, stage_b]

workflow:
  auto_cancel:
    on_job_failure: all

job1:
  stage: stage_a
  script: sleep 60

job2:
  stage: stage_a
  script:
    - sleep 30
    - exit 1

job3:
  stage: stage_b
  script:
    - sleep 30

In this example, if job2 fails, job1 is canceled if it is still running and job3 does not start.

Related topics:

• Auto-cancel the parent pipeline from a downstream pipeline

workflow:name

{{< history >}}

• Introduced in GitLab 15.5 with a flag named pipeline_name. Disabled by default.
• Enabled on GitLab.com and GitLab Self-Managed in GitLab 15.7.
• Generally available in GitLab 15.8. Feature flag pipeline_name removed.

{{< /history >}}

You can use name in workflow: to define a name for pipelines.

All pipelines are assigned the defined name. Any leading or trailing spaces in the name are removed.

Supported values:

• A string.
• CI/CD variables.
• A combination of both.

Examples of workflow:name:

A simple pipeline name with a predefined variable:

workflow:
  name: 'Pipeline for branch: $CI_COMMIT_BRANCH'

A configuration with different pipeline names depending on the pipeline conditions:

variables:
  PROJECT1_PIPELINE_NAME: 'Default pipeline name'  # A default is not required

workflow:
  name: '$PROJECT1_PIPELINE_NAME'
  rules:
    - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/'
      variables:
        PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PROJECT1_PIPELINE_NAME: 'MR pipeline: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # For default branch pipelines, use the default name

Additional details:

• If the name is an empty string, the pipeline is not assigned a name. A name consisting of only CI/CD variables could evaluate to an empty string if all the variables are also empty.
• workflow:rules:variables become default variables available in all jobs, including trigger jobs which forward variables to downstream pipelines by default. If the downstream pipeline uses the same variable, the variable is overwritten by the upstream variable value. Be sure to either:
  • Use a unique variable name in every project's pipeline configuration, like PROJECT1_PIPELINE_NAME.
  • Use inherit:variables in the trigger job and list the exact variables you want to forward to the downstream pipeline.

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.

Supported values: You can use some of the same keywords as job-level rules:

• rules: if.
• rules: changes.
• rules: exists.
• when, can only be always or never when used with workflow.
• variables.

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.
• start_in, allow_failure, and needs are not supported in workflow:rules, but do not cause a syntax violation. Though they have no effect, do not use them in workflow:rules as it could cause syntax failures in the future. See issue 436473 for more details.

Related topics:

• Common if clauses for workflow:rules.
• Use rules to run merge request pipelines.

workflow:rules:variables

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 top level as a default variable, the workflow variable takes precedence and overrides the default variable.

Keyword type: Global keyword.

Supported values: 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_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        DEPLOY_VARIABLE: "deploy-production"  # Override globally-defined DEPLOY_VARIABLE
    - if: $CI_COMMIT_BRANCH =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Define a new variable.
    - if: $CI_COMMIT_BRANCH                   # Run the pipeline in other cases

job1:
  variables:
    DEPLOY_VARIABLE: "job1-default-deploy"
  rules:
    - if: $CI_COMMIT_BRANCH == $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.

Additional details:

• workflow:rules:variables become default variables available in all jobs, including trigger jobs which forward variables to downstream pipelines by default. If the downstream pipeline uses the same variable, the variable is overwritten by the upstream variable value. Be sure to either:
  • Use unique variable names in every project's pipeline configuration, like PROJECT1_VARIABLE_NAME.
  • Use inherit:variables in the trigger job and list the exact variables you want to forward to the downstream pipeline.

workflow:rules:auto_cancel

{{< history >}}

• Introduced in GitLab 16.8 with a flag named ci_workflow_auto_cancel_on_new_commit. Disabled by default.
• Enabled on GitLab.com and GitLab Self-Managed in GitLab 16.9.
• Generally available in GitLab 16.10. Feature flag ci_workflow_auto_cancel_on_new_commit removed.
• on_job_failure option for workflow:rules introduced in GitLab 16.10 with a flag named auto_cancel_pipeline_on_job_failure. Disabled by default.
• on_job_failure option for workflow:rules generally available in GitLab 16.11. Feature flag auto_cancel_pipeline_on_job_failure removed.

{{< /history >}}

Use workflow:rules:auto_cancel to configure the behavior of the workflow:auto_cancel:on_new_commit or the workflow:auto_cancel:on_job_failure features.

Supported values:

• on_new_commit: workflow:auto_cancel:on_new_commit
• on_job_failure: workflow:auto_cancel:on_job_failure

Example of workflow:rules:auto_cancel:

workflow:
  auto_cancel:
    on_new_commit: interruptible
    on_job_failure: all
  rules:
    - if: $CI_COMMIT_REF_PROTECTED == 'true'
      auto_cancel:
        on_new_commit: none
        on_job_failure: none
    - when: always                  # Run the pipeline in other cases

test-job1:
  script: sleep 10
  interruptible: false

test-job2:
  script: sleep 10
  interruptible: true

In this example, workflow:auto_cancel:on_new_commit is set to interruptible and workflow:auto_cancel:on_job_failure is set to all for all jobs by default. But if a pipeline runs for a protected branch, the rule overrides the default with on_new_commit: none and on_job_failure: none. For example, if a pipeline is running for:

• A non-protected branch and a new commit is pushed, test-job1 continues to run and test-job2 is canceled.
• A protected branch and a new commit is pushed, both test-job1 and test-job2 continue to run.

Header keywords

Some keywords must be defined in a header section of a YAML configuration file. The header must be at the top of the file, separated from the rest of the configuration with ---.

spec

{{< history >}}

• Introduced in GitLab 15.11 as a beta feature.

{{< /history >}}

Add a spec section to the header of a YAML file to configure the behavior of a pipeline when a configuration is added to the pipeline with the include keyword.

Specs must be declared at the top of a configuration file, in a header section separated from the rest of the configuration with ---.

spec:inputs

You can use spec:inputs to define inputs for the CI/CD configuration.

Use the interpolation format $[[ inputs.input-id ]] to reference the values outside of the header section. Inputs are evaluated and interpolated when the configuration is fetched during pipeline creation. When using inputs, interpolation completes before the configuration is merged with the contents of the .gitlab-ci.yml file.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: A hash of strings representing the expected inputs.

Example of spec:inputs:

spec:
  inputs:
    environment:
    job-stage:
---

scan-website:
  stage: $[[ inputs.job-stage ]]
  script: ./scan-website $[[ inputs.environment ]]

Additional details:

• Inputs are mandatory unless you use spec:inputs:default to set a default value. Avoid mandatory inputs unless you only use inputs with include:inputs.
• Inputs expect strings unless you use spec:inputs:type to set a different input type.
• A string containing an interpolation block must not exceed 1 MB.
• The string inside an interpolation block must not exceed 1 KB.
• You can define input values when running a new pipeline.

Related topics:

• Define input parameters with spec:inputs.

spec:inputs:default

{{< history >}}

• Introduced in GitLab 15.11 as a beta feature.

{{< /history >}}

Inputs are mandatory when included, unless you set a default value with spec:inputs:default.

Use default: '' to have no default value.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: A string representing the default value, or ''.

Example of spec:inputs:default:

spec:
  inputs:
    website:
    user:
      default: 'test-user'
    flags:
      default: ''
---
# The pipeline configuration would follow...

In this example:

• website is mandatory and must be defined.
• user is optional. If not defined, the value is test-user.
• flags is optional. If not defined, it has no value.

Additional details:

• The pipeline fails with a validation error when the input:
  • Uses both default and options, but the default value is not one of the listed options.
  • Uses both default and regex, but the default value does not match the regular expression.
  • Value does not match the type.

spec:inputs:description

{{< history >}}

• Introduced in GitLab 16.5.

{{< /history >}}

Use description to give a description to a specific input. The description does not affect the behavior of the input and is only used to help users of the file understand the input.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: A string representing the description.

Example of spec:inputs:description:

spec:
  inputs:
    flags:
      description: 'Sample description of the `flags` input details.'
---
# The pipeline configuration would follow...

spec:inputs:options

{{< history >}}

• Introduced in GitLab 16.6.

{{< /history >}}

Inputs can use options to specify a list of allowed values for an input. The limit is 50 options per input.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: An array of input options. Only string and number type inputs can be used with options.

Example of spec:inputs:options:

spec:
  inputs:
    environment:
      options:
        - development
        - staging
        - production
---
# The pipeline configuration would follow...

In this example:

• environment is mandatory and must be defined with one of the values in the list.

Additional details:

• The pipeline fails with a validation error when:
  • The input uses both options and default, but the default value is not one of the listed options.
  • Any of the input options do not match the type, which can be either string or number, but not boolean when using options.

spec:inputs:regex

{{< history >}}

• Introduced in GitLab 16.5.

{{< /history >}}

Use spec:inputs:regex to specify a regular expression that the input must match.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: Must be a regular expression.

Example of spec:inputs:regex:

spec:
  inputs:
    version:
      regex: ^v\d\.\d+(\.\d+)?$
---
# The pipeline configuration would follow...

In this example, inputs of v1.0 or v1.2.3 match the regular expression and pass validation. An input of v1.A.B does not match the regular expression and fails validation.

Additional details:

• inputs:regex can only be used with a type of string, not number or boolean.
• Do not enclose the regular expression with the / character. For example, use regex.*, not /regex.*/.
• inputs:regex uses RE2 to parse regular expressions.
• Validation of the input against the regular expression happens before variable expansion. If the input text includes a variable name, the raw value of the input (the variable name) is validated, not the variable value.

spec:inputs:rules

{{< history >}}

• Introduced in GitLab 18.7.

{{< /history >}}

Use spec:inputs:rules to define conditional options and default values for an input based on the values of other inputs.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: An array of rule objects. Each rule can have:

• if: A conditional expression to check input values, using $[[ inputs.input-id ]] syntax.
• options: An array of allowed values for the input.
• default: The default value for the input when this rule matches. Use default: null to allow users to enter their own value for the input.

Example of spec:inputs:rules:

spec:
  inputs:
    environment:
      options: ['development', 'production']
      default: 'development'

    instance_type:
      description: 'VM instance size'
      rules:
        - if: $[[ inputs.environment ]] == 'development'
          options: ['small', 'medium']
          default: 'small'
        - if: $[[ inputs.environment ]] == 'production'
          options: ['large', 'xlarge']
          default: 'large'
---

deploy:
  script: echo "Deploying $[[ inputs.instance_type ]] instance"

In this example, when environment is development, users can only select small or medium instances. When environment is production, only large or xlarge instances are available.

Additional details:

• Rules are evaluated in order. The first rule with a matching if condition is used.
• A rule without an if condition acts as a fallback when no other rules match.
• Fallback rules must define options with at least one value.
• All rules with options must also define a default value that exists in the options list.
• You cannot use both rules and top-level options or default for the same input.

Related topics:

• Define conditional input options with spec:inputs:rules.

spec:inputs:type

By default, inputs expect strings. Use spec:inputs:type to set a different required type for inputs.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: Can be one of:

• array, to accept an array of inputs.
• string, to accept string inputs (default when not defined).
• number, to only accept numeric inputs.
• boolean, to only accept true or false inputs.

Example of spec:inputs:type:

spec:
  inputs:
    job_name:
    website:
      type: string
    port:
      type: number
    available:
      type: boolean
    array_input:
      type: array
---
# The pipeline configuration would follow...

spec:include

{{< history >}}

• Introduced in GitLab 18.6 with a flag named ci_file_inputs. Disabled by default.
• Generally available in GitLab 18.9. Feature flag ci_file_inputs removed.

{{< /history >}}

Use spec:include to include external input definitions from other files. You can share and reuse input definitions across multiple pipeline configurations.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: An array of include locations. Supports local, remote, and project includes only.

Example of spec:include:

spec:
  include:
    - local: /shared-inputs.yml
  inputs:
    environment:
      default: production
---

deploy:
  script: echo "Deploying to $[[ inputs.environment ]]"

With multiple includes from different sources:

spec:
  include:
    - local: /base-inputs.yml
    - remote: 'https://example.com/ci/common-inputs.yml'
    - project: 'my-group/shared-configs'
      ref: main
      file: '/ci/team-inputs.yml'
  inputs:
    environment:
      default: production
---

deploy:
  script: echo "Deploying to $[[ inputs.environment ]]"

Additional details:

• You cannot use spec:include in CI/CD components.
• External input files must contain only the inputs key. Other keys cause validation errors.
• External inputs are merged first, then inline inputs are applied.
• Inline inputs cannot have the same name as included inputs.
• When you include multiple input files, they are merged in the order specified.
• Supports local, remote, and project include types. Does not support template, component, or artifact includes.

Related topics:

• Use inputs from external files.

spec:component

{{< history >}}

• Introduced in GitLab 18.6 as a beta with a flag named ci_component_context_interpolation. Enabled by default.
• Generally available in GitLab 18.7. Feature flag ci_component_context_interpolation removed.

{{< /history >}}

Use spec:component to define which component context data is available for interpolation in a CI/CD component.

Component context provides metadata about the component itself, such as its name, version, and the commit SHA. This allows component templates to reference their own metadata dynamically.

Use the interpolation format $[[ component.field-name ]] to reference component context values in the component template.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: An array of strings. Each string must be one of:

• name: The component name as specified in the component path.
• sha: The commit SHA of the component.
• version: The resolved semantic version from the catalog resource. Returns null if:
  • The component is not a catalog resource.
  • The reference is a branch name or commit SHA (not a released version).
• reference: The original reference specified after @ in the component path. For example, 1.0, ~latest, a branch name, or a commit SHA.

Example of spec:component:

spec:
  component: [name, version, reference]
  inputs:
    stage:
      default: build
---

build-image:
  stage: $[[ inputs.stage ]]
  image: registry.example.com/$[[ component.name ]]:$[[ component.version ]]
  script:
    - echo "Building with component version $[[ component.version ]]"
    - echo "Component reference: $[[ component.reference ]]"

Additional details:

• The version field resolves to the actual semantic version when using:
  • A full version like @1.0.0 (returns 1.0.0)
  • A partial version like @1.0 (returns the latest matching version, for example 1.0.2)
  • @~latest (returns the latest version)
• The reference field always returns the exact value specified after @:
  • @1.0 returns 1.0 (while version might return 1.0.2)
  • @~latest returns ~latest (while version returns the actual version number)
  • @abc123 returns abc123 (while version returns null)

Related topics:

• Use component context in components.

spec:description

{{< history >}}

• Introduced in GitLab 18.10.

{{< /history >}}

Use spec:description to provide a short description of the component. The description is displayed in the CI/CD Catalog on the component details page, above the inputs table.

Keyword type: Header keyword. spec must be declared at the top of the configuration file, in a header section.

Supported values: A string describing the component.

Example of spec:description:

spec:
  description: "A description of the component visible to users in the CI/CD Catalog."
  inputs:
    stage:
      default: test
---
scan-job:
  stage: $[[ inputs.stage ]]
  script: ./run-scan.sh

Job keywords

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

after_script

{{< history >}}

• Running after_script commands for canceled jobs introduced in GitLab 17.0.

{{< /history >}}

Use after_script to define an array of commands to run last, after a job's before_script and script sections complete. after_script commands also run when:

• The job is canceled while the before_script or script sections are still running.
• The job fails with failure type of script_failure, but not other failure types.

Job configuration and default configuration does not merge together. If the pipeline has default:after_script defined, and the job also has after_script, the job configuration takes precedence and the default configuration is not used.

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

Supported values: An array including:

• Single line commands.
• Long commands split over multiple lines.
• YAML anchors.

CI/CD variables are supported.

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:

• Have the current working directory set back to the default (according to the variables which define how the runner processes Git requests).
• Don't have access to changes done by commands defined in the before_script or script, including:
  • Command aliases and variables exported in script scripts.
  • Changes outside of the working tree (depending on the runner executor), like software installed by a before_script or script script.
• Have a separate timeout. For GitLab Runner 16.4 and later, this defaults to 5 minutes, and can be configured with the RUNNER_AFTER_SCRIPT_TIMEOUT variable. In GitLab 16.3 and earlier, the timeout is hard-coded to 5 minutes.
• Don't affect the job's exit code. If the script section succeeds and the after_script times out or fails, the job exits with code 0 (Job Succeeded).
• For jobs that time out:
  • after_script commands do not execute by default.
  • You can configure timeout values to ensure after_script runs by setting appropriate RUNNER_SCRIPT_TIMEOUT and RUNNER_AFTER_SCRIPT_TIMEOUT values that don't exceed the job's timeout.
• Using after_script at the top level, but not in the default section, is deprecated.

Execution timing and file inclusion:

after_script commands execute before cache and artifact upload operations.

• If you configured artifact collection:
  • Files created or modified in after_script are included in artifacts.
  • Changes made in after_script are included in cache uploads.
• Any files that after_script creates or modifies in the specified cache or artifact paths are captured and uploaded. You can use this timing for scenarios like:
  • Generating test reports or coverage data after the main script.
  • Creating summary files or logs.
  • Post-processing build outputs.

In the following example, the only files that are not included are those created or modified after the artifact or cache upload stages:

job:
  script:
    - echo "main" > output.txt
    - build_something

  after_script:
    - echo "modified in after_script" >> output.txt  # This WILL be in the artifact
    - generate_test_report > report.html            # This WILL be in the artifact

  artifacts:
    paths:
      - output.txt
      - report.html

  cache:
    paths:
      - output.txt  # Will include the "modified in after_script" line

For more information, see job execution flow.

Related topics:

• Use after_script with default to define a default array of commands that should run after all jobs.
• You can configure a job to skip after_script commands if the job is canceled.
• You can ignore non-zero exit codes.
• Use color codes with after_script to make job logs easier to review.
• Create custom collapsible sections to simplify job log output.
• You can ignore errors in after_script.

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 ({{< icon name="status_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 jobs that use when: manual inside rules.
• false in all other cases.

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

Supported values:

• 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
  environment: 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.
• If allow_failure: true is set, the job is always considered successful, and later jobs with when: on_failure don't start if this job fails.
• 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

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.

Supported values:

• 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

{{< history >}}

• Updated in GitLab Runner 18.1. During the caching process, symlinks are no longer followed, which happened in some edge cases with previous GitLab Runner versions.

{{< /history >}}

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 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.

Job configuration and default configuration does not merge together. If the pipeline has default:artifacts defined, and the job also has artifacts, the job configuration takes precedence and the default configuration is not used.

Read more about artifacts.

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.

Supported values:

• An array of file paths, relative to the project directory.
• You can use Wildcards that use glob patterns and doublestar.Glob patterns.
• For GitLab Pages job:
  • In GitLab 17.10 and later, the pages.publish path is automatically appended to artifacts:paths, so you don't need to specify it again.
  • In GitLab 17.10 and later, when the pages.publish path is not specified, the public directory is automatically appended to artifacts:paths.

CI/CD variables are supported.

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, the artifacts file is named artifacts, which becomes artifacts.zip when downloaded.

Related topics:

• To restrict which jobs a specific job fetches artifacts from, see dependencies.
• Create job artifacts.

artifacts:exclude

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.

Supported values:

• An array of file paths, relative to the project directory.
• You can use Wildcards that use glob or 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:

• Exclude files from job artifacts.

artifacts:expire_in

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

• Artifacts from the latest job, unless keeping the latest job artifacts is disabled at the project level or instance-wide.

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.

Supported values: 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:
  • Select Keep on the job page.
  • Set the value of expire_in to never.
• If the expiry time is too short, jobs in later stages of a long pipeline might try to fetch expired artifacts from earlier jobs. If the artifacts are expired, jobs that try to fetch them fail with a could not retrieve the needed artifacts error. Set the expiry time to be longer, or use dependencies in later jobs to ensure they don't try to fetch expired artifacts.
• artifacts:expire_in doesn't affect GitLab Pages deployments. To configure Pages deployments' expiry, use pages.expire_in.

artifacts:expose_as

Use the artifacts:expose_as keyword to expose 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.

Supported values:

• 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:

• You can use expose_as only once per job, with a maximum of 10 jobs per merge request.
• Glob patterns are not supported.
• Artifacts are always sent to GitLab. They are displayed in the UI unless artifacts:paths values:
  • Use CI/CD variables.
  • Define a directory, but do not end with /. For example, directory/ works with artifacts:expose_as, but directory does not.
• If artifacts:paths only includes a single file, the link opens the file directly. In all other cases, the link opens the artifacts browser.
• Linked files are downloaded by default. If GitLab Pages is enabled, you can preview some artifacts file extensions directly in your browser. See Browse the contents of the artifacts archive for details.

Related topics:

• Expose job artifacts in the merge request UI.

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.

Supported values:

• The name of the artifacts archive. CI/CD variables are supported. Must be combined with artifacts:paths.

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:

• Use CI/CD variables to define the artifacts configuration

artifacts:public

{{< history >}}

• Updated in GitLab 15.10. Artifacts created with artifacts:public before 15.10 are not guaranteed to remain private after this update.
• Generally available in GitLab 16.7. Feature flag non_public_artifacts removed.

{{< /history >}}

[!note] artifacts:public is now superseded by artifacts:access which has more options.

Use artifacts:public to control whether job artifacts in public pipelines are available for download with the GitLab UI and API by anonymous users, or Guest and Reporter roles.

[!warning] This option only affects GitLab UI and API access. CI/CD jobs using job tokens could still access artifacts with the runner API, regardless of this setting. To restrict job token access, configure your project's CI/CD visibility settings to Only project members.

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

Supported values:

• true (default): Artifacts in a job in public pipelines are available for download by anyone, including anonymous users, or Guest and Reporter roles.
• false: Artifacts in the job are only available for download by users with the Developer, Maintainer, or Owner role.

Example of artifacts:public:

job:
  artifacts:
    public: false

artifacts:access

{{< history >}}

• Introduced in GitLab 16.11.
• maintainer option introduced in GitLab 18.4.

{{< /history >}}

Use artifacts:access to determine who can access the job artifacts from the GitLab UI or API. This option does not prevent you from forwarding artifacts to downstream pipelines.

You cannot use artifacts:public and artifacts:access in the same job.

[!warning] This option only affects GitLab UI and API access. CI/CD jobs using job tokens could still access artifacts with the runner API, regardless of this setting. To restrict job token access, configure your project's CI/CD visibility settings to Only project members.

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

Supported values:

• all (default): Artifacts in a job in public pipelines are available for download by anyone, including anonymous, guest, and reporter users.
• developer: Artifacts in the job are only available for download by users with the Developer, Maintainer, or Owner role.
• maintainer: Artifacts in the job are only available for download by users with the Maintainer or Owner role.
• none: Artifacts in the job are not available for download by anyone.

Example of artifacts:access:

job:
  artifacts:
    access: 'developer'

Additional details:

• artifacts:access affects all artifacts:reports too, so you can also restrict access to artifacts for reports.

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.

Supported values:

• See list of available artifacts reports types.

Example of artifacts:reports:

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

Additional details:

• Combining reports in parent pipelines using artifacts from child pipelines is not supported. For more information, see epic 8205.
• To be able to browse and download the report output files, include the artifacts:paths keyword. This uploads and stores the artifact twice.
• Artifacts created for artifacts: reports are always uploaded, regardless of the job results (success or failure). You can use artifacts:expire_in to set an expiration date for the artifacts.

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.

Supported values:

• true or false (default if not defined).

Example of artifacts:untracked:

Save all Git untracked files:

job:
  artifacts:
    untracked: true

Related topics:

• Add untracked files to artifacts.

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.

Supported values:

• 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

Additional details:

• The artifacts created for artifacts:reports are always uploaded, regardless of the job results (success or failure). artifacts:when does not change this behavior.

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.

Supported values: An array including:

• Single line commands.
• Long commands split over multiple lines.
• YAML anchors.

CI/CD variables are supported.

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.
• Using before_script at the top level, but not in the default section, is deprecated.

Related topics:

• Use before_script with default to define a default array of commands that should run before the script commands in all jobs.
  • Job configuration and default configuration does not merge together. If the pipeline has default:before_script defined, and the job also has before_script, the job configuration takes precedence and the default configuration is not used.
• You can ignore non-zero exit codes.
• Use color codes with before_script to make job logs easier to review.
• Create custom collapsible sections to simplify job log output.

cache

{{< history >}}

• Introduced in GitLab 15.0, caches are not shared between protected and unprotected branches.
• Updated in GitLab Runner 18.1. During the caching process, symlinks are no longer followed, which happened in some edge cases with previous GitLab Runner versions.

{{< /history >}}

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.

Caches are:

• Shared between pipelines and jobs.
• By default, not shared between protected and unprotected branches.
• Restored before artifacts.
• Limited to a maximum of four different caches.

You can disable caching for specific jobs, for example to override:

• A default cache defined with default.
• The configuration for a job added with include.

Job configuration and default configuration does not merge together. If the pipeline has default:cache defined, and the job also has cache, the job configuration takes precedence and the default configuration is not used.

For more information about caches, see Caching in GitLab CI/CD.

Using cache at the top level, but not in the default section, is deprecated.

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.

Supported values:

• An array of paths relative to the project directory ($CI_PROJECT_DIR). You can use wildcards that use glob and doublestar.Glob patterns.

CI/CD variables are supported.

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

Additional details:

• The cache:paths keyword includes files even if they are untracked or in your .gitignore file.

Related topics:

• See the CI/CD caching examples for more cache:paths examples.

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.

Must be used with cache: paths, or nothing is cached.

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

Supported values:

• A string.
• A predefined CI/CD variable.
• A combination of both.

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:

• You can specify a fallback cache key to use if the specified cache:key is not found.
• You can use multiple cache keys in a single job.
• See the CI/CD caching examples for more cache:key examples.

cache:key:files

Use cache:key:files to generate a new cache key when the content of the specified files change. If the content remains unchanged, the cache key remains consistent across branches and pipelines. You can reuse 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.

Supported values:

• An array of up to two file paths or patterns.

CI/CD variables are not supported.

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 content of the listed files. If a file doesn't exist, it's ignored in the key calculation. If none of the specified files exist, the fallback key is default.
• Wildcard patterns like **/package.json can be used.
• A maximum of two files can be specified. For updates on increasing the number of allowed paths or patterns, see issue 301161.

cache:key:files_commits

Use cache:key:files_commits to generate a new cache key when the latest commit changes for the specified files. cache:key:files_commits cache keys change whenever the specified files have a new commit, even if the file content remains identical.

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

Supported values:

• An array of up to two file paths or patterns.

Example of cache:key:files_commits:

cache-job:
  script:
    - echo "This job uses a commit-based cache."
  cache:
    key:
      files_commits:
        - package.json
        - yarn.lock
    paths:
      - node_modules

This example creates a cache based on the commit history of package.json and yarn.lock. If the commit history changes for these files, a new cache key is computed and a new cache is created.

Additional details:

• The cache key is a SHA computed from the most recent commit for each specified file.
• If a file doesn't exist, it's ignored in the key calculation.
• If none of the specified files exist, the fallback key is default.
• Cannot be used together with cache:key:files in the same cache configuration.

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.

Supported values:

• A string.
• A predefined CI/CD variable.
• A combination of both.

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. Untracked files include files that are:

• Ignored due to .gitignore configuration.
• Created, but not added to the checkout with git add.

Caching untracked files can create unexpectedly large caches if the job downloads:

• Dependencies, like gems or node modules, which are usually untracked.
• Artifacts from a different job. Files extracted from the artifacts are untracked by default.

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

Supported values:

• 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. Use cache:paths to cache any specific files, including tracked files, or files that are outside of the working directory, and use cache: untracked to also cache all untracked files. For example:

  yamlCopy

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

  In this example, the job caches all untracked files in the repository, as well as all the files in binaries/. If there are untracked files in binaries/, they are covered by both keywords.

cache:unprotect

{{< history >}}

• Introduced in GitLab 15.8.

{{< /history >}}

Use cache:unprotect to set a cache to be shared between protected and unprotected branches.

[!warning] When set to true, users without access to protected branches can read and write to cache keys used by protected branches.

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

Supported values:

• true or false (default).

Example of cache:unprotect:

rspec:
  script: test
  cache:
    unprotect: true

cache:when

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

Must be used with cache: paths, or nothing is cached.

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

Supported values:

• 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.

Must be used with cache: paths, or nothing is cached.

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

Supported values:

• pull
• push
• pull-push (default)
• CI/CD variables.

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..."

Related topics:

• You can use a variable to control a job's cache policy.

cache:fallback_keys

Use cache:fallback_keys to specify a list of keys to try to restore cache from if there is no cache found for the cache:key. Caches are retrieved in the order specified in the fallback_keys section.

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

Supported values:

• An array of cache keys

Example of cache:fallback_keys:

rspec:
  script: rspec
  cache:
    key: gems-$CI_COMMIT_REF_SLUG
    paths:
      - rspec/
    fallback_keys:
      - gems
    when: 'always'

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+)?.

Supported values:

• An RE2 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. Because it uses RE2 syntax, all groups must be non-capturing.

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 the regular expression: \d+(?:\.\d+)?. The sample regex can match a code coverage of 67.89.

Additional details:

• You can find regex examples in Code Coverage.
• 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. See issue 280818 for more details.

dast_configuration

{{< details >}}

• Tier: Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

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.

Supported values: One each of site_profile and scanner_profile.

• Use site_profile to specify the site profile to be used in the job.
• Use scanner_profile to specify the scanner profile to be used in the job.

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:

• Site profile.
• Scanner profile.

dependencies

Use the dependencies keyword to define a list of specific jobs to fetch artifacts from. The specified jobs must all be in earlier stages. You can also set a job to download no artifacts at all.

When dependencies is not defined in a job, all jobs in earlier stages are considered dependent and the job fetches all artifacts from those jobs.

To fetch artifacts from a job in the same stage, you must use needs:artifacts. You should not combine dependencies with needs in the same job.

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

Supported values:

• 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
  environment: production

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.

Supported values: 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.

Supported values: 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.

Supported values: 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:

• See environment:action for more details and an example.

environment:action

Use the action keyword to specify how the job interacts with the environment.

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

Supported values: One of the following keywords:

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

{{< history >}}

• CI/CD variable support introduced in GitLab 15.4.
• Updated to support prepare, access and verify environment actions in GitLab 17.7.

{{< /history >}}

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.

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

• 168 hours
• 7 days
• one week
• never

CI/CD variables are supported.

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.

The auto_stop_in keyword can be used for all environment actions except stop. Some actions can be used to reset the scheduled stop time for the environment. For more information, see Access an environment for preparation or verification purposes.

Related topics:

• Environments auto-stop documentation.

environment:kubernetes

{{< history >}}

• agent keyword introduced in GitLab 17.6.
• namespace and flux_resource_path keywords introduced in GitLab 17.7.
• namespace and flux_resource_path keywords deprecated in GitLab 18.4.
• dashboard:namespace and dashboard:flux_resource_path keywords introduced in GitLab 18.4.

{{< /history >}}

Use the kubernetes keyword to configure the dashboard for Kubernetes and GitLab-managed Kubernetes resources for an environment.

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

Supported values:

• agent: A string specifying the GitLab agent for Kubernetes. The format is path/to/agent/project:agent-name. If the agent is connected to the project running the pipeline, use $CI_PROJECT_PATH:agent-name.
• dashboard:namespace: A string representing the Kubernetes namespace where the environment is deployed. The namespace must be set together with the agent keyword. namespace is deprecated.
• dashboard:flux_resource_path: A string representing the full path to the Flux resource, such as a HelmRelease. The Flux resource must be set together with the agent and dashboard:namespace keywords. flux_resource_path is deprecated.
• managed_resources: A hash with the enabled keyword to configure the GitLab-managed Kubernetes resources for the environment.
  • managed_resources:enabled: A boolean value indicating whether GitLab-managed Kubernetes resources are enabled for the environment.
• dashboard: A hash with the dashboard:namespace and dashboard:flux_resource_path keywords to configure the dashboard for Kubernetes for the environment.

Example of environment:kubernetes:

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      agent: path/to/agent/project:agent-name
      dashboard:
        namespace: my-namespace
        flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

Example of environment:kubernetes when disabling managed resources:

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      agent: path/to/agent/project:agent-name
      managed_resources:
        enabled: false
      dashboard:
        namespace: my-namespace
        flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

This configuration:

• Sets up the deploy job to deploy to the production environment.
• Associates the agent named agent-name with the environment.
• Configures the dashboard for Kubernetes for an environment with the namespace my-namespace and the flux_resource_path set to helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource.

Additional details:

• To use the dashboard, you must install the GitLab agent for Kubernetes and configure user_access for the environment's project or its parent group.
• The user running the job must be authorized to access the cluster agent. Otherwise, the dashboard ignores the agent, namespace, and flux_resource_path attributes.
• If you only want to set the agent, you do not have to set the namespace, and cannot set flux_resource_path. However, this configuration lists all namespaces in a cluster in the dashboard for Kubernetes.

environment:deployment_tier

{{< history >}}

• Support for CI/CD variables added in GitLab 18.5.

{{< /history >}}

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.

Supported values: One of the following:

• production
• staging
• testing
• development
• other
• 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:deployment_tier:

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

Additional details:

• Environments created from this job definition are assigned a tier based on this value.
• Existing environments don't have their tier updated if this value is added later. Existing environments must have their tier updated via the Environments API.

Related topics:

• Deployment tier of environments.

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.

Supported values:

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

Example of extends:

.tests:
  stage: test
  image: ruby:3.0

rspec:
  extends: .tests
  script: rake rspec

rubocop:
  extends: .tests
  script: bundle exec rubocop

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 combined configuration is equivalent to these jobs:

rspec:
  stage: test
  image: ruby:3.0
  script: rake rspec

rubocop:
  stage: test
  image: ruby:3.0
  script: bundle exec rubocop

Additional details:

• 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 previous example, .tests is a hidden job, but you can extend configuration from regular jobs as well.

Related topics:

• Reuse configuration sections by using extends.
• Use extends to reuse configuration from included configuration files.

hooks

{{< history >}}

• Introduced in GitLab 15.6 with a flag named ci_hooks_pre_get_sources_script. Disabled by default.
• Generally available in GitLab 15.10. Feature flag ci_hooks_pre_get_sources_script removed.

{{< /history >}}

Use hooks to specify lists of commands to execute on the runner at certain stages of job execution, like before retrieving the Git repository.

Job configuration and default configuration does not merge together. If the pipeline has default:hooks defined, and the job also has hooks, the job configuration takes precedence and the default configuration is not used.

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

Supported values:

• A hash of hooks and their commands. Available hooks: pre_get_sources_script.

hooks:pre_get_sources_script

{{< history >}}

• Introduced in GitLab 15.6 with a flag named ci_hooks_pre_get_sources_script. Disabled by default.
• Generally available in GitLab 15.10. Feature flag ci_hooks_pre_get_sources_script removed.

{{< /history >}}

Use hooks:pre_get_sources_script to specify a list of commands to execute on the runner before cloning the Git repository and any submodules. You can use it for example to:

• Adjust the Git configuration.
• Export tracing variables.

Supported values: An array including:

• Single line commands.
• Long commands split over multiple lines.
• YAML anchors.

CI/CD variables are supported.

Example of hooks:pre_get_sources_script:

job1:
  hooks:
    pre_get_sources_script:
      - echo 'hello job1 pre_get_sources_script'
  script: echo 'hello job1 script'

Related topics:

• GitLab Runner configuration

identity

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com
• Status: Beta

{{< /details >}}

{{< history >}}

• Introduced in GitLab 16.9 with a flag named google_cloud_support_feature_flag. This feature is in beta.
• Enabled on GitLab.com in GitLab 17.1. Feature flag google_cloud_support_feature_flag removed.

{{< /history >}}

This feature is in beta.

Use identity to authenticate with third party services using identity federation.

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

Supported values: An identifier. Supported providers:

• google_cloud: Google Cloud. Must be configured with the Google Cloud IAM integration.

Example of identity:

job_with_workload_identity:
  identity: google_cloud
  script:
    - gcloud compute instances list

Related topics:

• Workload Identity Federation.
• Google Cloud IAM integration.

id_tokens

{{< history >}}

• Introduced in GitLab 15.7.

{{< /history >}}

Use id_tokens to create ID tokens to authenticate with third party services. All JWTs created this way support OIDC authentication. The required aud sub-keyword is used to configure the aud claim for the JWT.

Job configuration and default configuration does not merge together. If the pipeline has default:id_tokens defined, and the job also has id_tokens, the job configuration takes precedence and the default configuration is not used.

Supported values:

• Token names with their aud claims. aud supports:
  • A single string.
  • An array of strings.
  • CI/CD variables.

Example of id_tokens:

job_with_id_tokens:
  id_tokens:
    ID_TOKEN_1:
      aud: https://vault.example.com
    ID_TOKEN_2:
      aud:
        - https://gcp.com
        - https://aws.com
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - command_to_authenticate_with_vault $ID_TOKEN_1
    - command_to_authenticate_with_aws $ID_TOKEN_2
    - command_to_authenticate_with_gcp $ID_TOKEN_2

Related topics:

• ID token authentication.
• Connect to cloud services.
• Keyless signing with Sigstore.

image

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

Job configuration and default configuration does not merge together. If the pipeline has default:image defined, and the job also has image, the job configuration takes precedence and the default configuration is not used.

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

Supported values: 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>

CI/CD variables are supported.

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.

Additional details:

• Using image at the top level, but not in the default section, is deprecated.

Related topics:

• Run your CI/CD jobs in Docker containers.

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.

Supported values: 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>

CI/CD variables are supported.

Example of image:name:

test-job:
  image:
    name: "registry.example.com/my/image:latest"
  script: echo "Hello world"

Related topics:

• Run your CI/CD jobs in Docker containers.

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 Dockerfile ENTRYPOINT directive, 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.

Supported values:

• A string.

Example of image:entrypoint:

test-job:
  image:
    name: super/sql:experimental
    entrypoint: [""]
  script: echo "Hello world"

Related topics:

• Override the entrypoint of an image.

image:docker

{{< history >}}

• Introduced in GitLab 16.7. Requires GitLab Runner 16.7 or later.
• user input option introduced in GitLab 16.8.

{{< /history >}}

Use image:docker to pass options to runners using the Docker executor or the Kubernetes executor. This keyword does not work with other executor types.

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

Supported values:

A hash of options for the Docker executor, which can include:

• platform: Selects the architecture of the image to pull. When not specified, the default is the same platform as the host runner.
• user: Specify the username or UID to use when running the container.

Example of image:docker:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    docker:
      platform: arm64/v8
      user: dave

Additional details:

• image:docker:platform maps to the docker pull --platform option.
• image:docker:user maps to the docker run --user option.

image:kubernetes

{{< history >}}

• Introduced in GitLab 18.0. Requires GitLab Runner 17.11 or later.
• user input option introduced in GitLab Runner 17.11.
• user input option extended to support uid:gid format in GitLab 18.0.

{{< /history >}}

Use image:kubernetes to pass options to the GitLab Runner Kubernetes executor. This keyword does not work with other executor types.

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

Supported values:

A hash of options for the Kubernetes executor, which can include:

• user: Specify the username or UID to use when the container runs. You can also use it to set GID by using the UID:GID format.

Example of image:kubernetes with only UID:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    kubernetes:
      user: "1001"

Example of image:kubernetes with both UID and GID:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    kubernetes:
      user: "1001:1001"

image:pull_policy

{{< history >}}

• Introduced in GitLab 15.1 with a flag named ci_docker_image_pull_policy. Disabled by default.
• Enabled on GitLab.com and GitLab Self-Managed in GitLab 15.2.
• Generally available in GitLab 15.4. Feature flag ci_docker_image_pull_policy removed.
• Requires GitLab Runner 15.1 or later.

{{< /history >}}

The pull policy that the runner uses to fetch the Docker image.

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

Supported values:

• A single pull policy, or multiple pull policies in an array. Can be always, if-not-present, or never.

Examples of image:pull_policy:

job1:
  script: echo "A single pull policy."
  image:
    name: ruby:3.0
    pull_policy: if-not-present

job2:
  script: echo "Multiple pull policies."
  image:
    name: ruby:3.0
    pull_policy: [always, if-not-present]

Additional details:

• If the runner does not support the defined pull policy, the job fails with an error similar to: ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never]).

Related topics:

• Run your CI/CD jobs in Docker containers.
• Configure how runners pull images.
• Set multiple pull policies.

inputs

{{< history >}}

• Introduced in GitLab 18.10.

{{< /history >}}

Use inputs to define typed and validated inputs for a job. Job inputs can be overridden when manually running or retrying a job.

Job inputs are parameters that provide type safety and validation. Unlike CI/CD variables, only inputs explicitly defined in the job can be specified when running or retrying the job. All job input names must be predefined.

Reference job input values with the ${{ job.inputs.INPUT_NAME }} Moa expression syntax.

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

Supported values:

A hash of input names, where each input is configured with one or more subkeys:

• default (required)
• type
• options
• description
• regex

Example of inputs:

test_job:
  inputs:
    test_suite:
      default: unit
      description: Which test suite to run
      options: [unit, integration, e2e]
    parallel_count:
      type: number
      default: 5
      description: Number of parallel test runners
    verbose:
      type: boolean
      default: false
      description: Enable verbose test output
  script:
    - 'echo "Running ${{ job.inputs.test_suite }} tests"'
    - 'if [ "${{ job.inputs.verbose }}" == "true" ]; then export TEST_VERBOSE=1; fi'
    - ./run_tests.sh --suite ${{ job.inputs.test_suite }} --parallel ${{ job.inputs.parallel_count }}

Additional details:

• Job inputs are validated when the job is created and when you try to retry a job with new input values. If validation fails, the job does not start.
• Job inputs are scoped to the job where they are defined and cannot be accessed by other jobs.
• For a complete list of keywords that support job inputs, see where you can use job inputs.

inputs:default

All job inputs must have a default value defined with default.

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

Supported values: Any value matching the input's type.

Example of inputs:default:

test_job:
  inputs:
    environment:
      default: staging
    timeout:
      type: number
      default: 30

inputs:type

Use type to define the data type of the input value.

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

Supported values:

• string (default)
• number
• boolean
• array.

Example of inputs:type:

test_job:
  inputs:
    count:
      type: number
      default: 5
    enabled:
      type: boolean
      default: true

inputs:description

Use description to provide information about the input's purpose. The description does not affect the input's behavior.

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

Supported values: A string.

Example of inputs:description:

deploy_job:
  inputs:
    environment:
      default: staging
      description: Target deployment environment

inputs:options

Use options to specify a list of allowed values for an input.

The input value must match one of the listed options exactly (case-sensitive). Validation fails if the value does not match an option.

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

Supported values: An array of allowed values.

Example of inputs:options:

deploy_job:
  inputs:
    environment:
      default: staging
      options: [development, staging, production]

inputs:regex

Use regex to specify a regular expression pattern that the input value must match.

Validation fails if the value does not match the regular expression.

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

Supported values: A regular expression string.

Example of inputs:regex:

deploy_job:
  inputs:
    version:
      default: v1.0.0
      regex: ^v\d+\.\d+\.\d+$

In this example, an input value of v1.1.1 passes the regex validation, but an input of v1.1.1-beta does not.

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.

Supported values:

• 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 default variables keywords.

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

Supported values:

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

Example of inherit:variables:

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

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

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

Additional details:

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

interruptible

{{< history >}}

• Support for trigger jobs introduced in GitLab 16.8.

{{< /history >}}

Use interruptible to configure the auto-cancel redundant pipelines feature to cancel a job before it completes if a new pipeline on the same ref starts for a newer commit. If the feature is disabled, the keyword has no effect. The new pipeline must be for a commit with new changes. For example, the Auto-cancel redundant pipelines feature has no effect if you select New pipeline in the UI to run a pipeline for the same commit.

The behavior of the Auto-cancel redundant pipelines feature can be controlled by the workflow:auto_cancel:on_new_commit setting.

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

Supported values:

• true or false (default).

Example of interruptible with the default behavior:

workflow:
  auto_cancel:
    on_new_commit: conservative # the default behavior

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.

Example of interruptible with the auto_cancel:on_new_commit:interruptible setting:

workflow:
  auto_cancel:
    on_new_commit: 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 "Can be canceled."
  interruptible: true

In this example, a new pipeline causes a running pipeline to cancel step-1 and step-3 if they are running or pending.

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 canceled, to prevent partial deployments.
• When using the default behavior or workflow:auto_cancel:on_new_commit: conservative:
  • A job that has not started yet is always considered interruptible: true, regardless of the job's configuration. The interruptible configuration is only considered after the job starts.
  • Running pipelines are only canceled if all running jobs are configured with interruptible: true or no jobs configured with interruptible: false have started at any time. After a job with interruptible: false starts, the entire pipeline is no longer considered interruptible.
  • If the pipeline triggered a downstream pipeline, but no job with interruptible: false in the downstream pipeline has started yet, the downstream pipeline is also canceled.
• You can add an optional manual job with interruptible: false in the first stage of a pipeline to allow users to manually prevent a pipeline from being automatically canceled. After a user starts the job, the pipeline cannot be canceled by the Auto-cancel redundant pipelines feature.
• When using interruptible with a trigger job:
  • The triggered downstream pipeline is never affected by the trigger job's interruptible configuration.
  • If workflow:auto_cancel is set to conservative, the trigger job's interruptible configuration has no effect.
  • If workflow:auto_cancel is set to interruptible, a trigger job with interruptible: true can be automatically canceled.

needs

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.

Supported values:

• An array of jobs (maximum of 50 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..."
  environment: 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: lint, linux:build, linux:rspec, mac:build, mac:rspec.

Additional details:

• The maximum number of jobs that a single job can have in the needs array is limited:
  • For GitLab.com, the limit is 50. For more information, see issue 350398.
  • For GitLab Self-Managed and GitLab Dedicated, the default limit is 50. This limit can be changed by updating the CI/CD limits in the Admin area.
• If needs refers to a job that uses the parallel keyword, it depends on all jobs created in parallel, not just one job. It also downloads artifacts from all the parallel jobs by default. If the artifacts have the same name, they overwrite each other and only the last one downloaded is saved.
  • To have needs refer to a subset of parallelized jobs (and not all of the parallelized jobs), use the needs:parallel:matrix keyword.
• You can refer to jobs in the same stage as the job you are configuring.
• If needs refers to a job that might not be added to a pipeline because of only, except, or rules, the pipeline might fail to create. Use the needs:optional keyword to resolve a failed pipeline creation.
• If a pipeline has jobs with needs: [] and jobs in the .pre stage, they will all start as soon as the pipeline is created. Jobs with needs: [] start immediately, and jobs in the .pre stage also start immediately.

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.

Supported values:

• true (default) or false.

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:

• You should not combine needs with dependencies in the same job.

needs:project

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Use needs:project to download artifacts from up to five jobs in other pipelines. The artifacts are downloaded from the latest successful specified job for the specified ref. To specify multiple jobs, add each as separate array items under the needs keyword.

If there is a pipeline running for the ref, a job with needs:project does not wait for the pipeline to complete. Instead, the artifacts are downloaded from the latest successful run of the specified job.

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

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

Supported values:

• needs:project: A full project path, including namespace and group.
• job: The job to download artifacts from.
• ref: The ref to download artifacts from.
• artifacts: Must be true to download artifacts.

Examples of needs:project:

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

In this example, build_job downloads the artifacts from the latest successful build-1 and build-2 jobs on the main branches in the group/project-name and group/project-name-2 projects.

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:

• To download artifacts from a different pipeline in the current project, set project to be the same as the current project, but use a different ref than the current pipeline. Concurrent pipelines running on the same ref could override the artifacts.
• The user running the pipeline must have the Reporter, Developer, Maintainer, or Owner role for the group or project, or the group/project must have public visibility.
• You can't use needs:project in the same job as trigger.
• When using needs:project to download artifacts from another pipeline, the job does not wait for the needed job to complete. Using needs to wait for jobs to complete is limited to jobs in the same pipeline. Make sure that the needed job in the other pipeline completes before the job that needs it tries to download the artifacts.
• You can't download artifacts from jobs that run in parallel.
• Support CI/CD variables in project, job, and ref.

Related topics:

• To download artifacts between parent-child pipelines, use needs:pipeline:job.

needs:pipeline:job

A child pipeline can download artifacts from a successfully finished job in its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy.

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

Supported values:

• needs:pipeline: A pipeline ID. Must be a pipeline present in the same parent-child pipeline hierarchy.
• job: The job to download artifacts from.

Example of needs:pipeline:job:

• Parent pipeline (.gitlab-ci.yml):

  yamlCopy

  stages:
    - build
    - test
  
  create-artifact:
    stage: build
    script: echo "sample artifact" > artifact.txt
    artifacts:
      paths: [artifact.txt]
  
  child-pipeline:
    stage: test
    trigger:
      include: child.yml
      strategy: mirror
    variables:
      PARENT_PIPELINE_ID: $CI_PIPELINE_ID
  

• Child pipeline (child.yml):

  yamlCopy

  use-artifact:
    script: cat artifact.txt
    needs:
      - pipeline: $PARENT_PIPELINE_ID
        job: create-artifact
  

In this example, the create-artifact job in the parent pipeline creates some artifacts. The child-pipeline job triggers a child pipeline, and passes the CI_PIPELINE_ID variable to the child pipeline as a new PARENT_PIPELINE_ID variable. The child pipeline can use that variable in needs:pipeline to download artifacts from the parent pipeline. Having the create-artifact and child-pipeline jobs in subsequent stages ensures that the use-artifact job only executes when create-artifact has successfully finished.

Additional details:

• The pipeline attribute does not accept the current pipeline ID ($CI_PIPELINE_ID). To download artifacts from a job in the current pipeline, use needs:artifacts.
• You cannot use needs:pipeline:job in a trigger job, or to fetch artifacts from a multi-project pipeline. To fetch artifacts from a multi-project pipeline use needs:project.
• The job listed in needs:pipeline:job must complete with a status of success or the artifacts can't be fetched. Issue 367229 proposes to allow fetching artifacts from any job with artifacts.

needs:optional

To need a job that sometimes does not exist in the pipeline, add optional: true to the needs configuration. If not defined, optional: false is the default.

Jobs that use rules, only, or except and that are added with include might not always be added to a pipeline. GitLab checks the needs relationships before starting a pipeline:

• If the needs entry has optional: true and the needed job is present in the pipeline, the job waits for it to complete before starting.
• If the needed job is not present, the job can start when all other needs requirements are met.
• If the needs section contains only optional jobs, and none are added to the pipeline, the job starts immediately (the same as an empty needs entry: needs: []).
• If a needed job has optional: false, but it was not added to the pipeline, the pipeline fails to start with an error similar to: 'job1' job needs 'job2' job, but it was not added to the pipeline.

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

Example of needs:optional:

build-job:
  stage: build

test-job1:
  stage: test

test-job2:
  stage: test
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
    - job: test-job1
  environment: production

review-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
  environment: review

In this example:

• build-job, test-job1, and test-job2 start in stage order.
• When the branch is the default branch, test-job2 is added to the pipeline, so:
  • deploy-job waits for both test-job1 and test-job2 to complete.
  • review-job waits for test-job2 to complete.
• When the branch is not the default branch, test-job2 is not added to the pipeline, so:
  • deploy-job waits for only test-job1 to complete, and does not wait for the missing test-job2.
  • review-job has no other needed jobs and starts immediately (at the same time as build-job), like needs: [].

Additional details:

• You cannot use needs:optional with needs:parallel:matrix.

needs:pipeline

You can mirror the pipeline status from an upstream pipeline to a job by using the needs:pipeline keyword. The latest pipeline status from the default branch is replicated to the job.

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

Supported values:

• A full project path, including namespace and group. If the project is in the same group or namespace, you can omit them from the project keyword. For example: project: group/project-name or project: project-name.

Example of needs:pipeline:

upstream_status:
  stage: test
  needs:
    pipeline: other/project

Additional details:

• If you add the job keyword to needs:pipeline, the job no longer mirrors the pipeline status. The behavior changes to needs:pipeline:job.

needs:parallel:matrix

{{< history >}}

• Introduced in GitLab 16.3.

{{< /history >}}

Jobs can use parallel:matrix to run a job multiple times in parallel in a single pipeline, but with different variable values for each instance of the job.

Use needs:parallel:matrix to execute jobs out-of-order depending on parallelized jobs.

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

Supported values: An array of hashes of matrix identifiers:

• The identifiers and values must be selected from the identifiers and values defined in the parallel:matrix job.
• You can use matrix expressions.

Example of needs:parallel:matrix:

linux:build:
  stage: build
  script: echo "Building linux..."
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2

linux:rspec:
  stage: test
  needs:
    - job: linux:build
      parallel:
        matrix:
          - PROVIDER: aws
            STACK: app1
  script: echo "Running rspec on linux..."

The previous example generates the following jobs:

linux:build: [aws, monitoring]
linux:build: [aws, app1]
linux:build: [aws, app2]
linux:rspec

The linux:rspec job runs as soon as the linux:build: [aws, app1] job finishes.

Additional details:

• You cannot use needs:parallel:matrix with needs:optional.

• The order of the matrix identifiers in needs:parallel:matrix must match the order of the matrix variables in the needed job. For example, reversing the order of the variables in the linux:rspec job in the previous example would be invalid:

  yamlCopy

  linux:rspec:
    stage: test
    needs:
      - job: linux:build
        parallel:
          matrix:
            - STACK: app1        # The variable order does not match `linux:build` and is invalid.
              PROVIDER: aws
    script: echo "Running rspec on linux..."
  

Related topics:

• Specify a parallelized job using needs with multiple parallelized jobs.
• Matrix expressions in needs:parallel:matrix.

pages

Use pages to define a GitLab Pages job that uploads static content to GitLab. The content is then published as a website.

You must:

• Define pages: true to publish a directory named public
• Alternatively, define pages.publish if want to use a different content directory.
• Have a non-empty index.html file in the root of the content directory.

Keyword type: Job keyword or Job name (deprecated). You can use it only as part of a job.

Supported Values:

• A boolean. Uses the default configuration when set to true
• A hash of configuration options, see the following sections for details.

Example of pages:

create-pages:
  stage: deploy
  script:
    - mv my-html-content public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

This example renames the my-html-content/ directory to public/. This directory is exported as an artifact and published with GitLab Pages.

Example using a configuration hash:

create-pages:
  stage: deploy
  script:
    - echo "nothing to do here"
  pages:  # specifies that this is a Pages job and publishes the default public directory
    publish: my-html-content
    expire_in: "1 week"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

This example does not move the directory, but uses the publish property directly. It also configures the pages deployment to be unpublished after a week.

Additional details:

• Using pages as a job name is deprecated.
• To use pages as a job name without triggering a Pages deployment, set the pages property to false

pages.publish

{{< history >}}

• Introduced in GitLab 16.1.
• Changed to allow variables when passed to publish property in GitLab 17.9.
• Moved the publish property under the pages keyword in GitLab 17.9.
• Appended the pages.publish path automatically to artifacts:paths in GitLab 17.10.

{{< /history >}}

Use pages.publish to configure the content directory of a pages job.

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

Supported values: A path to a directory containing the Pages content. In GitLab 17.10 and later, if not specified, the default public directory is used and if specified, this path is automatically appended to artifacts:paths.

Example of pages.publish:

create-pages:
  stage: deploy
  script:
    - npx @11ty/eleventy --input=path/to/eleventy/root --output=dist
  pages:
    publish: dist  # this path is automatically appended to artifacts:paths
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

This example uses Eleventy to generate a static website and output the generated HTML files into a the dist/ directory. This directory is exported as an artifact and published with GitLab Pages.

It is also possible to use variables in the pages.publish field. For example:

create-pages:
  stage: deploy
  script:
    - mkdir -p $CUSTOM_FOLDER/$CUSTOM_PATH
    - cp -r public $CUSTOM_FOLDER/$CUSTOM_SUBFOLDER
  pages:
    publish: $CUSTOM_FOLDER/$CUSTOM_SUBFOLDER  # this path is automatically appended to artifacts:paths
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  variables:
    CUSTOM_FOLDER: "custom_folder"
    CUSTOM_SUBFOLDER: "custom_subfolder"

The publish path specified must be relative to the build root.

Additional details:

• The top-level publish keyword is deprecated and must now be nested under the pages keyword

pages.path_prefix

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
• Status: Beta

{{< /details >}}

{{< history >}}

• Introduced in GitLab 16.7 as an experiment with a flag named pages_multiple_versions_setting, disabled by default.
• Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 17.4.
• Changed to allow periods in GitLab 17.8.
• Generally available in GitLab 17.9. Feature flag pages_multiple_versions_setting removed.

{{< /history >}}

Use pages.path_prefix to configure a path prefix for parallel deployments of GitLab Pages.

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

Supported values:

• A string
• CI/CD variables
• A combination of both

The given value is converted to lowercase and shortened to 63 bytes. Everything except alphanumeric characters or periods is replaced with a hyphen. Leading and trailing hyphens or periods are not permitted.

Example of pages.path_prefix:

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  pages:  # specifies that this is a Pages job and publishes the default public directory
    path_prefix: "$CI_COMMIT_BRANCH"

In this example, a different pages deployment is created for each branch.

pages.expire_in

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Introduced in GitLab 17.4.
• Support for variables introduced in GitLab 17.11.

{{< /history >}}

Use expire_in to specify how long a deployment should be available before it expires. After the deployment is expired, it's deactivated by a cron job running every 10 minutes.

By default, parallel deployments expire automatically after 24 hours. To disable this behavior, set the value to never.

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

Supported values: The expiry time. If no unit is provided, the time is in seconds. Variables are also supported. 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
• $DURATION

Example of pages.expire_in:

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  pages:  # specifies that this is a Pages job and publishes the default public directory
    expire_in: 1 week

parallel

{{< history >}}

• Introduced in GitLab 15.9, the maximum value for parallel is increased from 50 to 200.

{{< /history >}}

Use parallel to run a job multiple times in parallel in a single pipeline.

Multiple runners must exist, or a single runner must be configured to run multiple jobs concurrently.

Parallel jobs are named sequentially from job_name 1/N to job_name N/N.

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

Supported values:

• A numeric value from 1 to 200.

Example of parallel:

test:
  script: rspec
  parallel: 5

This example creates 5 jobs that run in parallel, named test 1/5 to test 5/5.

Additional details:

• Every parallel job has a CI_NODE_INDEX and CI_NODE_TOTAL predefined CI/CD variable set.
• A pipeline with jobs that use parallel might:
  • Create more jobs running in parallel than available runners. Excess jobs are queued and marked pending while waiting for an available runner.
  • Fail with a job_activity_limit_exceeded error if creating the pipeline would cause the total number of jobs across all active pipelines to exceed the instance limit.

Related topics:

• Parallelize large jobs.

parallel:matrix

{{< history >}}

• Introduced in GitLab 15.9, the maximum number of permutations is increased from 50 to 200.

{{< /history >}}

Use parallel:matrix to run a job multiple times in parallel in a single pipeline, but with different variable values for each instance of the job.

Multiple runners must exist, or a single runner must be configured to run multiple jobs concurrently.

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

Supported values: An array of hashes of variables:

• The matrix identifiers, which become the variable names, can use only numbers, letters, and underscores (_).
• The values must be either a string, or an array of strings.
• The number of permutations cannot exceed 200.

Example of parallel:matrix:

deploystacks:
  stage: deploy
  script:
    - bin/deploy
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2
      - PROVIDER: [gcp, vultr]
        STACK: [data, processing]
  environment: $PROVIDER/$STACK

The example generates 7 parallel deploystacks jobs, each with different values for PROVIDER and STACK:

• deploystacks: [aws, monitoring]
• deploystacks: [aws, app1]
• deploystacks: [aws, app2]
• deploystacks: [gcp, data]
• deploystacks: [gcp, processing]
• deploystacks: [vultr, data]
• deploystacks: [vultr, processing]

Additional details:

• parallel:matrix jobs add the matrix values to the job names to differentiate the jobs from each other. However, long values can cause job names to exceed the 255-character limit. For more information, see epic 11791.

• You cannot use the matrix values as variables for rules:if.

• You cannot create multiple matrix configurations with the same values but different names. Job names are generated from the matrix values, not the names, so matrix entries with identical values generate identical job names that overwrite each other.

  For example, this test configuration would try to create two series of identical jobs, but the OS2 versions overwrite the OS versions:

  yamlCopy

  test:
    parallel:
      matrix:
        - OS: [ubuntu]
          PROVIDER: [aws, gcp]
        - OS2: [ubuntu]
          PROVIDER: [aws, gcp]
  

Related topics:

• Run a one-dimensional matrix of parallel jobs.
• Run a matrix of triggered parallel jobs.
• Select different runner tags for each parallel matrix job.
• Matrix expressions in needs:parallel:matrix.

release

Use release to create a release.

The release job must have access to the glab CLI, which must be in the $PATH.

If you use the Docker executor, you can use this image from the GitLab container registry: registry.gitlab.com/gitlab-org/cli:latest

If you use the Shell executor or similar, install glab CLI on the server where the runner is registered.

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

Supported values: The release subkeys:

• tag_name
• tag_message (optional)
• name (optional)
• description
• ref (optional)
• milestones (optional)
• released_at (optional)
• assets:links (optional)

Example of release keyword:

release_job:
  stage: release
  image: registry.gitlab.com/gitlab-org/cli:latest
  rules:
    - if: $CI_COMMIT_TAG                  # Run this job when a tag is created manually
  script:
    - echo "Running the release job."
  release:
    tag_name: $CI_COMMIT_TAG
    name: 'Release $CI_COMMIT_TAG'
    description: 'Release created using the CLI.'

This example creates a release:

• When you push a Git tag.
• When you add a Git tag in the UI at Code > Tags.

Additional details:

• Release jobs must include the script keyword. A release job can use the output from script commands. If you don't need the script, you can use a placeholder:

  yamlCopy

  script:
    - echo "release job"
  

  For more details, see issue 223856, which aims to remove this restriction.

• The release section executes after the script keyword and before the after_script.

• A release is created only if the job's main script succeeds.

• If the release already exists, it is not updated and the job with the release keyword fails.

Related topics:

• CI/CD example of the release keyword.
• Create multiple releases in a single pipeline.
• Use a custom SSL CA certificate authority.

release:tag_name

Required. The Git tag for the release.

If the tag does not exist in the project yet, it is created at the same time as the release. New tags use the SHA associated with the pipeline.

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

Supported values:

• A tag name.

CI/CD variables are supported.

Example of release:tag_name:

To create a release when a new tag is added to the project:

• Use the $CI_COMMIT_TAG CI/CD variable as the tag_name.
• Use rules:if to configure the job to run only for new tags.

job:
  script: echo "Running the release job for the new tag."
  release:
    tag_name: $CI_COMMIT_TAG
    description: 'Release description'
  rules:
    - if: $CI_COMMIT_TAG

To create a release and a new tag at the same time, your rules should not configure the job to run only for new tags. A semantic versioning example:

job:
  script: echo "Running the release job and creating a new tag."
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: 'Release description'
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

release:tag_message

If the tag does not exist, the newly created tag is annotated with the message specified by tag_message. If omitted, a lightweight tag is created.

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

Supported values:

• A text string.

Example of release:tag_message:

  release_job:
    stage: release
    release:
      tag_name: $CI_COMMIT_TAG
      description: 'Release description'
      tag_message: 'Annotated tag message'

release:name

The release name. If omitted, it is populated with the value of release: tag_name.

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

Supported values:

• A text string.

Example of release:name:

  release_job:
    stage: release
    release:
      name: 'Release $CI_COMMIT_TAG'

release:description

The long description of the release.

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

Supported values:

• A string with the long description.
• The path to a file that contains the description.
  • The file location must be relative to the project directory ($CI_PROJECT_DIR).
  • If the file is a symbolic link, it must be in the $CI_PROJECT_DIR.
  • The ./path/to/file and filename can't contain spaces.

Example of release:description:

job:
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: './path/to/CHANGELOG.md'

Additional details:

• The description is evaluated by the shell that runs glab. You can use CI/CD variables to define the description, but some shells use different syntax to reference variables. Similarly, some shells might require special characters to be escaped. For example, backticks (`) might need to be escaped with a backslash (\).

release:ref

The ref for the release, if the release: tag_name doesn't exist yet.

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

Supported values:

• A commit SHA, another tag name, or a branch name.

release:milestones

The title of each milestone the release is associated with.

release:released_at

The date and time when the release is ready.

Supported values:

• A date enclosed in quotes and expressed in ISO 8601 format.

Example of release:released_at:

released_at: '2021-03-15T08:00:00Z'

Additional details:

• If it is not defined, the current date and time is used.

release:assets:links

Use release:assets:links to include asset links in the release.

Example of release:assets:links:

assets:
  links:
    - name: 'asset1'
      url: 'https://example.com/assets/1'
    - name: 'asset2'
      url: 'https://example.com/assets/2'
      filepath: '/pretty/url/1' # optional
      link_type: 'other' # optional

resource_group

Use resource_group to create a resource group that ensures a job is mutually exclusive across different pipelines for the same project.

For example, if multiple jobs that belong to the same resource group are queued simultaneously, only one of the jobs starts. The other jobs wait until the resource_group is free.

Resource groups behave similar to semaphores in other programming languages.

You can choose a process mode to strategically control the job concurrency for your deployment preferences. The default process mode is unordered. To change the process mode of a resource group, use the API to send a request to edit an existing resource group.

You can define multiple resource groups per environment. For example, when deploying to physical devices, you might have multiple physical devices. Each device can be deployed to, but only one deployment can occur per device at any given time.

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

Supported values:

• Only letters, digits, -, _, /, $, {, }, ., and spaces. It can't start or end with /. CI/CD variables are supported.

Example of resource_group:

deploy-to-production:
  script: deploy
  resource_group: production

In this example, two deploy-to-production jobs in two separate pipelines can never run at the same time. As a result, you can ensure that concurrent deployments never happen to the production environment.

Related topics:

• Pipeline-level concurrency control with cross-project/parent-child pipelines.

retry

Use retry to configure how many times a job is retried if it fails. If not defined, defaults to 0 and jobs do not retry.

When a job fails, the job is processed up to two more times, until it succeeds or reaches the maximum number of retries.

By default, all failure types cause the job to be retried. Use retry:when or retry:exit_codes to select which failures to retry on.

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

Supported values:

• 0 (default), 1, or 2.

Example of retry:

test:
  script: rspec
  retry: 2

test_advanced:
  script:
    - echo "Run a script that results in exit code 137."
    - exit 137
  retry:
    max: 2
    when: runner_system_failure
    exit_codes: 137

test_advanced will be retried up to 2 times if the exit code is 137 or if it had a runner system failure.

retry:when

Use retry:when with retry:max to retry jobs for only specific failure cases. retry:max is the maximum number of retries, like retry, and can be 0, 1, or 2.

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

Supported values:

• A single failure type, or an array of one or more failure types:

• always: Retry on any failure (default).
• unknown_failure: Retry when the failure reason is unknown.
• script_failure: Retry when:
  • The script failed.
  • The runner failed to pull the Docker image. For docker, docker+machine, kubernetes executors.
• api_failure: Retry on API failure.
• stuck_or_timeout_failure: Retry when the job got stuck or timed out.
• runner_system_failure: Retry if there is a runner system failure (for example, job setup failed).
• runner_unsupported: Retry if the runner is unsupported.
• stale_schedule: Retry if a delayed job could not be executed.
• job_execution_timeout: Retry if the script exceeded the maximum execution time set for the job.
• archived_failure: Retry if the job is archived and can't be run.
• unmet_prerequisites: Retry if the job failed to complete prerequisite tasks.
• scheduler_failure: Retry if the scheduler failed to assign the job to a runner.
• data_integrity_failure: Retry if there is an unknown job problem.

Example of retry:when (single failure type):

test:
  script: rspec
  retry:
    max: 2
    when: runner_system_failure

If there is a failure other than a runner system failure, the job is not retried.

Example of retry:when (array of failure types):

test:
  script: rspec
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure

retry:exit_codes

{{< history >}}

• Introduced in GitLab 16.10 with a flag named ci_retry_on_exit_codes. Disabled by default.
• Enabled on GitLab.com and GitLab Self-Managed in GitLab 16.11.
• Generally available in GitLab 17.5. Feature flag ci_retry_on_exit_codes removed.

{{< /history >}}

Use retry:exit_codes with retry:max to retry jobs for only specific failure cases. retry:max is the maximum number of retries, like retry, and can be 0, 1, or 2.

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

Supported values:

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

Example of retry:exit_codes:

test_job_1:
  script:
    - echo "Run a script that results in exit code 1. This job isn't retried."
    - exit 1
  retry:
    max: 2
    exit_codes: 137

test_job_2:
  script:
    - echo "Run a script that results in exit code 137. This job will be retried."
    - exit 137
  retry:
    max: 1
    exit_codes:
      - 255
      - 137

Related topics:

You can specify the number of retry attempts for certain stages of job execution using variables.

rules

Use rules to include or exclude jobs in pipelines.

Rules are evaluated when the pipeline is created, and evaluated in order. When a match is found, no more rules are checked and the job is either included or excluded from the pipeline depending on the configuration. If no rules match, the job is not added to the pipeline.

rules accepts an array of rules. Each rules must have at least one of:

• if
• changes
• exists
• when

Rules can also optionally be combined with:

• allow_failure
• needs
• variables
• interruptible

You can combine multiple keywords together for complex rules.

The job is added to the pipeline:

• If an if, changes, or exists rule matches, and is configured with when: on_success (default if not defined), when: delayed, or when: always.
• If a rule is reached that is only when: on_success, when: delayed, or when: always.

The job is not added to the pipeline:

• If no rules match.
• If a rule matches and has when: never.

For additional examples, see Specify when jobs run with rules.

rules:if

Use rules:if clauses to specify when to add a job to a pipeline:

• If an if statement is true, add the job to the pipeline.
• If an if statement is true, but it's combined with when: never, do not add the job to the pipeline.
• If an if statement is false, check the next rules item (if any more exist).

if clauses are evaluated:

• Based on the values of CI/CD variables or predefined CI/CD variables, with some exceptions.
• In order, following rules execution flow.

Keyword type: Job-specific and pipeline-specific. You can use it as part of a job to configure the job behavior, or with workflow to configure the pipeline behavior.

Supported values:

• A CI/CD variable expression.

Example of rules:if:

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH
      when: never
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/
      when: manual
      allow_failure: true
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME

Additional details:

• You cannot use nested variables with if. See issue 327780 for more details.
• If a rule matches and has no when defined, the rule uses the when defined for the job, which defaults to on_success if not defined.
• You can mix when at the job-level with when in rules. when configuration in rules takes precedence over when at the job-level.
• Unlike variables in script sections, variables in rules expressions are always formatted as $VARIABLE.
  • You can use rules:if with include to conditionally include other configuration files.
• CI/CD variables on the right side of =~ and !~ expressions are evaluated as regular expressions.

Related topics:

• Common if expressions for rules.
• Avoid duplicate pipelines.
• Use rules to run merge request pipelines.

rules:changes

Use rules:changes to specify when to add a job to a pipeline by checking for changes to specific files.

For new branch pipelines or when there is no Git push event, rules: changes always evaluates to true and the job always runs. Pipelines like tag pipelines, scheduled pipelines, and manual pipelines, all do not have a Git push event associated with them. To cover these cases, use rules: changes: compare_to to specify the branch to compare against the pipeline ref.

If you do not use compare_to, you should use rules: changes only with branch pipelines or merge request pipelines, though rules: changes still evaluates to true when creating a new branch. With:

• Merge request pipelines, rules:changes compares the changes with the target MR branch.
• Branch pipelines, rules:changes compares the changes with the previous commit on the branch.

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

Supported values:

An array including any number of:

• Paths to files. The file paths can include CI/CD variables.
• Wildcard paths for:
  • Single directories, for example path/to/directory/*.
  • A directory and all its subdirectories, for example path/to/directory/**/*.
• Wildcard glob paths for all files with the same extension or multiple extensions, for example *.md or path/to/directory/*.{rb,py,sh}.
• Wildcard paths to files in the root directory, or all directories, wrapped in double quotes. For example "*.json" or "**/*.json".

Example of rules:changes:

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile
      when: manual
      allow_failure: true

docker build alternative:
  variables:
    DOCKERFILES_DIR: 'path/to/dockerfiles'
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - $DOCKERFILES_DIR/**/*

In this example:

• If the pipeline is a merge request pipeline, check Dockerfile and the files in $DOCKERFILES_DIR/**/* for changes.
• If Dockerfile has changed, add the job to the pipeline as a manual job, and the pipeline continues running even if the job is not triggered (allow_failure: true).
• If a file in $DOCKERFILES_DIR/**/* has changed, add the job to the pipeline.
• If no listed files have changed, do not add either job to any pipeline (same as when: never).

Additional details:

• Glob patterns are interpreted with Ruby's File.fnmatch with the flags File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB.
• For performance reasons, GitLab performs a maximum of 50,000 checks against changes patterns or file paths. After the 50,000th check, rules with patterned globs always match. In other words, the changes rule always assumes a match when more than 50,000 files changed, or if there are fewer than 50,000 changed files but the changes rules are checked more than 50,000 times.
• A maximum of 50 patterns or file paths can be defined per rules:changes section.
• changes resolves to true if any of the matching files are changed (an OR operation).
• For additional examples, see Specify when jobs run with rules.
• You can use the $ character for both variables and paths. For example, if the $VAR variable exists, its value is used. If it does not exist, the $ is interpreted as being part of a path.
• Do not use ./, double slashes (//), or any other kind of relative path. Paths are matched with exact string comparison, they are not evaluated like in a shell.

Related topics:

• Jobs or pipelines can run unexpectedly when using rules: changes.

rules:changes:paths

{{< history >}}

• Introduced in GitLab 15.2.

{{< /history >}}

Use rules:changes to specify that a job only be added to a pipeline when specific files are changed, and use rules:changes:paths to specify the files.

rules:changes:paths is the same as using rules:changes without any subkeys. All additional details and related topics are the same.

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

Supported values:

• Same as rules:changes.

Example of rules:changes:paths:

docker-build-1:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile

docker-build-2:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile

In this example, both jobs have the same behavior.

rules:changes:compare_to

{{< history >}}

• Introduced in GitLab 15.3 with a flag named ci_rules_changes_compare. Enabled by default.
• Generally available in GitLab 15.5. Feature flag ci_rules_changes_compare removed.
• Support for CI/CD variables introduced in GitLab 17.2.

{{< /history >}}

Use rules:changes:compare_to to specify which ref to compare against for changes to the files listed under rules:changes:paths.

Keyword type: Job keyword. You can use it only as part of a job, and it must be combined with rules:changes:paths.

Supported values:

• A branch name, like main, branch1, or refs/heads/branch1.
• A tag name, like tag1 or refs/tags/tag1.
• A commit SHA, like 2fg31ga14b.

CI/CD variables are supported.

Example of rules:changes:compare_to:

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile
        compare_to: 'refs/heads/branch1'

In this example, the docker build job is only included when the Dockerfile has changed relative to refs/heads/branch1 and the pipeline source is a merge request event.

Additional details:

• Using compare_to in some situation can cause unexpected results:
  • With merged results pipelines, because the comparison base is an internal commit that GitLab creates.
  • In a forked project, see issue 424584.

Related topics:

• You can use rules:changes:compare_to to skip a job if the branch is empty.

rules:exists

{{< history >}}

• CI/CD variable support introduced in GitLab 15.6.
• Maximum number of checks against exists patterns or file paths increased from 10,000 to 50,000 in GitLab 17.7.
• Support for directory paths introduced in GitLab 18.2.

{{< /history >}}

Use exists to run a job when certain files or directories exist in the repository.

Keyword type: Job keyword. You can use it as part of a job or an include.

Supported values:

• An array of file or directory paths. Paths are relative to the project directory ($CI_PROJECT_DIR) and can't directly link outside it. File paths can use glob patterns and CI/CD variables.

Example of rules:exists:

job1:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        - Dockerfile

job2:
  variables:
    DOCKERPATH: "**/Dockerfile"
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        - $DOCKERPATH