diff options
Diffstat (limited to 'doc/ci/yaml/index.md')
| -rw-r--r-- | doc/ci/yaml/index.md | 4491 |
1 files changed, 2095 insertions, 2396 deletions
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 5702c7a7dfd..ed05ef08d02 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -16,6 +16,8 @@ This document lists the configuration options for your GitLab `.gitlab-ci.yml` f When you are editing your `.gitlab-ci.yml` file, you can validate it with the [CI Lint](../lint.md) tool. +If you are editing this page, make sure you follow the [CI/CD YAML reference style guide](../../development/cicd/cicd_reference_documentation_guide.md). + ## Keywords A GitLab CI/CD pipeline configuration includes: @@ -25,9 +27,9 @@ A GitLab CI/CD pipeline configuration includes: | Keyword | Description | |-------------------------|:------------| | [`default`](#default) | Custom default values for job keywords. | + | [`include`](#include) | Import configuration from other YAML files. | | [`stages`](#stages) | The names and order of the pipeline stages. | | [`workflow`](#workflow) | Control what types of pipeline run. | - | [`include`](#include) | Import configuration from other YAML files. | - [Jobs](../jobs/index.md) configured with [job keywords](#job-keywords): @@ -73,7 +75,7 @@ or import additional pipeline configuration. ### `default` You can set global defaults for some keywords. Jobs that do not define one or more -of the listed keywords use the value defined in the `default:` section. +of the listed keywords use the value defined in the `default` section. **Keyword type**: Global keyword. @@ -90,7 +92,7 @@ of the listed keywords use the value defined in the `default:` section. - [`tags`](#tags) - [`timeout`](#timeout) -**Example of `default`:** +**Example of `default`**: ```yaml default: @@ -106,7 +108,7 @@ rspec 2.7: In this example, `ruby:3.0` is the default `image` value for all jobs in the pipeline. The `rspec 2.7` job does not use the default, because it overrides the default with -a job-specific `image:` section: +a job-specific `image` section: **Additional details**: @@ -116,179 +118,6 @@ a job-specific `image:` section: takes precedence and is not replaced by the default. - Control inheritance of default keywords in jobs with [`inherit:default`](#inheritdefault). -### `stages` - -Use `stages` to define stages that contain groups of jobs. Use [`stage`](#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`](#stage-pre) -- `build` -- `test` -- `deploy` -- [`.post`](#stage-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. - -**Keyword type**: Global keyword. - -**Example of `stages`:** - -```yaml -stages: - - build - - test - - deploy -``` - -In this example: - -1. All jobs in `build` execute in parallel. -1. If all jobs in `build` succeed, the `test` jobs execute in parallel. -1. If all jobs in `test` succeed, the `deploy` jobs execute in parallel. -1. 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`](#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](../../user/project/settings/index.md#compliance-pipeline-configuration): - - 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`](#needs) keyword. - -### `workflow` - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5 - -Use [`workflow`](workflow.md) to control pipeline behavior. - -**Related topics**: - -- [`workflow: rules` examples](workflow.md#workflow-rules-examples) -- [Switch between branch pipelines and merge request pipelines](workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines) - -#### `workflow:rules` - -The `rules` keyword in `workflow` is similar to [`rules:` defined in jobs](#rules), -but controls whether or not a whole pipeline is created. - -When no rules evaluate to true, the pipeline does not run. - -**Possible inputs**: You can use some of the same keywords as job-level [`rules`](#rules): - -- [`rules: if`](#rulesif). -- [`rules: changes`](#ruleschanges). -- [`rules: exists`](#rulesexists). -- [`when`](#when), can only be `always` or `never` when used with `workflow`. -- [`variables`](#workflowrulesvariables). - -**Example of `workflow:rules`:** - -```yaml -workflow: - rules: - - if: $CI_COMMIT_MESSAGE =~ /-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 message does not have `-drafts` in it -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](../jobs/job_control.md#avoid-duplicate-pipelines) can occur. - -**Related topics**: - -- You can use the [`workflow:rules` templates](workflow.md#workflowrules-templates) to import - a preconfigured `workflow: rules` entry. -- [Common `if` clauses for `workflow:rules`](workflow.md#common-if-clauses-for-workflowrules). - -#### `workflow:rules:variables` - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/300997) in GitLab 14.1. - -You can use [`variables`](#variables) in `workflow:rules:` to define variables for -specific pipeline conditions. - -When the condition matches, the variable is created and can be used by all jobs -in the pipeline. If the variable is already defined at the global level, the `workflow` -variable takes precedence and overrides the global variable. - -**Keyword type**: Global keyword. - -**Possible inputs**: Variable name and value pairs: - -- The name can use only numbers, letters, and underscores (`_`). -- The value must be a string. - -**Example of `workflow:rules:variables`:** - -```yaml -variables: - DEPLOY_VARIABLE: "default-deploy" - -workflow: - rules: - - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH - variables: - DEPLOY_VARIABLE: "deploy-production" # Override globally-defined DEPLOY_VARIABLE - - if: $CI_COMMIT_REF_NAME =~ /feature/ - variables: - IS_A_FEATURE: "true" # Define a new variable. - - when: always # Run the pipeline in other cases - -job1: - variables: - DEPLOY_VARIABLE: "job1-default-deploy" - rules: - - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH - variables: # Override DEPLOY_VARIABLE defined - DEPLOY_VARIABLE: "job1-deploy-production" # at the job level. - - when: on_success # Run the job in other cases - script: - - echo "Run script with $DEPLOY_VARIABLE as an argument" - - echo "Run another script if $IS_A_FEATURE exists" - -job2: - script: - - echo "Run script with $DEPLOY_VARIABLE as an argument" - - echo "Run another script if $IS_A_FEATURE exists" -``` - -When the branch is the default branch: - -- job1's `DEPLOY_VARIABLE` is `job1-deploy-production`. -- job2's `DEPLOY_VARIABLE` is `deploy-production`. - -When the branch is `feature`: - -- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`, and `IS_A_FEATURE` is `true`. -- job2's `DEPLOY_VARIABLE` is `default-deploy`, and `IS_A_FEATURE` is `true`. - -When the branch is something else: - -- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`. -- job2's `DEPLOY_VARIABLE` is `default-deploy`. - ### `include` > [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4. @@ -372,8 +201,10 @@ use `include:file`. You can use `include:file` in combination with `include:proj **Keyword type**: Global keyword. -**Possible inputs**: A full path, relative to the root directory (`/`). -The YAML file must have the extension `.yml` or `.yaml`. +**Possible inputs**: + +- A full path, relative to the root directory (`/`). The YAML file must have the + extension `.yml` or `.yaml`. **Example of `include:file`**: @@ -428,10 +259,10 @@ Use `include:remote` with a full URL to include a file from a different location **Keyword type**: Global keyword. -**Possible inputs**: A public URL accessible by an HTTP/HTTPS `GET` request. -Authentication with the remote URL is not supported. +**Possible inputs**: -The YAML file must have the extension `.yml` or `.yaml`. +- A public URL accessible by an HTTP/HTTPS `GET` request. Authentication with the + remote URL is not supported. The YAML file must have the extension `.yml` or `.yaml`. **Example of `include:remote`**: @@ -454,7 +285,9 @@ Use `include:template` to include [`.gitlab-ci.yml` templates](https://gitlab.co **Keyword type**: Global keyword. -**Possible inputs**: [`.gitlab-ci.yml` templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). +**Possible inputs**: + +- [`.gitlab-ci.yml` templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). **Example of `include:template`**: @@ -477,224 +310,189 @@ include: - All [nested includes](includes.md#use-nested-includes) are executed only with the permission of the user, so it's possible to use `project`, `remote`, or `template` includes. -## Job keywords +### `stages` -The following topics explain how to use keywords to configure CI/CD pipelines. +Use `stages` to define stages that contain groups of jobs. Use [`stage`](#stage) +in a job to configure the job to run in a specific stage. -### `image` +If `stages` is not defined in the `.gitlab-ci.yml` file, the default pipeline stages are: -Use `image` to specify a Docker image that the job runs in. +- [`.pre`](#stage-pre) +- `build` +- `test` +- `deploy` +- [`.post`](#stage-post) -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +The order of the items in `stages` defines the execution order for jobs: -**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats: +- Jobs in the same stage run in parallel. +- Jobs in the next stage run after the jobs from the previous stage complete successfully. -- `<image-name>` (Same as using `<image-name>` with the `latest` tag) -- `<image-name>:<tag>` -- `<image-name>@<digest>` +**Keyword type**: Global keyword. -**Example of `image`**: +**Example of `stages`**: ```yaml -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 +stages: + - build + - test + - deploy ``` -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. +In this example: -**Related topics**: +1. All jobs in `build` execute in parallel. +1. If all jobs in `build` succeed, the `test` jobs execute in parallel. +1. If all jobs in `test` succeed, the `deploy` jobs execute in parallel. +1. If all jobs in `deploy` succeed, the pipeline is marked as `passed`. -- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). +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. -#### `image:name` +**Additional details**: -The name of the Docker image that the job runs in. Similar to [`image:`](#image) used by itself. +- If a job does not specify a [`stage`](#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](../../user/project/settings/index.md#compliance-pipeline-configuration): + - 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. -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +**Related topics**: -**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats: +- To make a job start earlier and ignore the stage order, use the [`needs`](#needs) keyword. -- `<image-name>` (Same as using `<image-name>` with the `latest` tag) -- `<image-name>:<tag>` -- `<image-name>@<digest>` +### `workflow` -**Example of `image:name`**: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5 -```yaml -image: - name: "registry.example.com/my/image:latest" -``` +Use [`workflow`](workflow.md) to control pipeline behavior. **Related topics**: -- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). +- [`workflow: rules` examples](workflow.md#workflow-rules-examples) +- [Switch between branch pipelines and merge request pipelines](workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines) -#### `image:entrypoint` +#### `workflow:rules` -Command or script to execute as the container's entry point. +The `rules` keyword in `workflow` is similar to [`rules` defined in jobs](#rules), +but controls whether or not a whole pipeline is created. -When the Docker container is created, the `entrypoint` is translated to the Docker `--entrypoint` option. -The syntax is similar to the [Dockerfile `ENTRYPOINT` directive](https://docs.docker.com/engine/reference/builder/#entrypoint), -where each shell token is a separate string in the array. +When no rules evaluate to true, the pipeline does not run. -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +**Possible inputs**: You can use some of the same keywords as job-level [`rules`](#rules): -**Possible inputs**: A string. +- [`rules: if`](#rulesif). +- [`rules: changes`](#ruleschanges). +- [`rules: exists`](#rulesexists). +- [`when`](#when), can only be `always` or `never` when used with `workflow`. +- [`variables`](#workflowrulesvariables). -**Example of `image:entrypoint`**: +**Example of `workflow:rules`**: ```yaml -image: - name: super/sql:experimental - entrypoint: [""] +workflow: + rules: + - if: $CI_COMMIT_MESSAGE =~ /-draft$/ + when: never + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` -**Related topics**: - -- [Override the entrypoint of an image](../docker/using_docker_images.md#override-the-entrypoint-of-an-image). - -#### `services` - -Use `services` to specify an additional Docker image to run scripts in. The [`services` image](../services/index.md) is linked -to the image specified in the [`image`](#image) keyword. - -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). - -**Possible inputs**: The name of the services 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>` +In this example, pipelines run if the commit message does not have `-drafts` in it +and the pipeline is for either: -**Example of `services`**: +- A merge request +- The default branch. -```yaml -default: - image: - name: ruby:2.6 - entrypoint: ["/bin/bash"] +**Additional details**: - services: - - name: my-postgres:11.7 - alias: db-postgres - entrypoint: ["/usr/local/bin/db-postgres"] - command: ["start"] +- If your rules match both branch pipelines (other than the default branch) and merge request pipelines, + [duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines) can occur. - before_script: - - bundle install +**Related topics**: -test: - script: - - bundle exec rake spec -``` +- You can use the [`workflow:rules` templates](workflow.md#workflowrules-templates) to import + a preconfigured `workflow: rules` entry. +- [Common `if` clauses for `workflow:rules`](workflow.md#common-if-clauses-for-workflowrules). -In this example, the job launches a Ruby container. Then, from that container, the job launches -another container that's running PostgreSQL. Then the job then runs scripts -in that container. +#### `workflow:rules:variables` -**Related topics**: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/300997) in GitLab 14.1. -- [Available settings for `services`](../services/index.md#available-settings-for-services). -- [Define `services` in the `.gitlab-ci.yml` file](../services/index.md#define-services-in-the-gitlab-ciyml-file). -- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). -- [Use Docker to build Docker images](../docker/using_docker_build.md). +You can use [`variables`](#variables) in `workflow:rules` to define variables for +specific pipeline conditions. -### `script` +When the condition matches, the variable is created and can be used by all jobs +in the pipeline. If the variable is already defined at the global level, the `workflow` +variable takes precedence and overrides the global variable. -Use `script` to specify commands for the runner to execute. +**Keyword type**: Global keyword. -All jobs except [trigger jobs](#trigger) require a `script` keyword. +**Possible inputs**: Variable name and value pairs: -**Keyword type**: Job keyword. You can use it only as part of a job. +- The name can use only numbers, letters, and underscores (`_`). +- The value must be a string. -**Possible inputs**: An array including: +**Example of `workflow:rules:variables`**: -- Single line commands. -- Long commands [split over multiple lines](script.md#split-long-commands). -- [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). +```yaml +variables: + DEPLOY_VARIABLE: "default-deploy" -**Example of `script`:** +workflow: + rules: + - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH + variables: + DEPLOY_VARIABLE: "deploy-production" # Override globally-defined DEPLOY_VARIABLE + - if: $CI_COMMIT_REF_NAME =~ /feature/ + variables: + IS_A_FEATURE: "true" # Define a new variable. + - when: always # Run the pipeline in other cases -```yaml job1: - script: "bundle exec rspec" + variables: + DEPLOY_VARIABLE: "job1-default-deploy" + rules: + - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH + variables: # Override DEPLOY_VARIABLE defined + DEPLOY_VARIABLE: "job1-deploy-production" # at the job level. + - when: on_success # Run the job in other cases + script: + - echo "Run script with $DEPLOY_VARIABLE as an argument" + - echo "Run another script if $IS_A_FEATURE exists" job2: script: - - uname -a - - bundle exec rspec + - echo "Run script with $DEPLOY_VARIABLE as an argument" + - echo "Run another script if $IS_A_FEATURE exists" ``` -**Additional details**: - -- When you use [these special characters in `script`](script.md#use-special-characters-with-script), you must use single quotes (`'`) or double quotes (`"`) . - -**Related topics**: - -- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes). -- [Use color codes with `script`](script.md#add-color-codes-to-script-output) - to make job logs easier to review. -- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) - to simplify job log output. - -#### `before_script` - -Use `before_script` to define an array of commands that should run before each job's -`script` commands, but after [artifacts](#artifacts) are restored. - -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). - -**Possible inputs**: An array including: +When the branch is the default branch: -- Single line commands. -- Long commands [split over multiple lines](script.md#split-long-commands). -- [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). +- job1's `DEPLOY_VARIABLE` is `job1-deploy-production`. +- job2's `DEPLOY_VARIABLE` is `deploy-production`. -**Example of `before_script`:** +When the branch is `feature`: -```yaml -job: - before_script: - - echo "Execute this command before any 'script:' commands." - script: - - echo "This command executes after the job's 'before_script' commands." -``` +- 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`. -**Additional details**: +When the branch is something else: -- Scripts you specify in `before_script` are concatenated with any scripts you specify - in the main [`script`](#script). The combined scripts execute together in a single shell. +- job1's `DEPLOY_VARIABLE` is `job1-default-deploy`. +- job2's `DEPLOY_VARIABLE` is `default-deploy`. -**Related topics**: +## Job keywords -- [Use `before_script` with `default`](script.md#set-a-default-before_script-or-after_script-for-all-jobs) - to define a default array of commands that should run before the `script` commands in all jobs. -- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes). -- [Use color codes with `before_script`](script.md#add-color-codes-to-script-output) - to make job logs easier to review. -- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) - to simplify job log output. +The following topics explain how to use keywords to configure CI/CD pipelines. -#### `after_script` +### `after_script` Use `after_script` to define an array of commands that run after each job, including failed jobs. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: An array including: @@ -702,7 +500,7 @@ Use `after_script` to define an array of commands that run after each job, inclu - Long commands [split over multiple lines](script.md#split-long-commands). - [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). -**Example of `after_script`:** +**Example of `after_script`**: ```yaml job: @@ -740,1168 +538,922 @@ If a job times out or is cancelled, the `after_script` commands do not execute. - [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) to simplify job log output. -### `stage` +### `allow_failure` -Use `stage` to define which [stage](#stages) a job runs in. Jobs in the same -`stage` can execute in parallel (see **Additional details**). +Use `allow_failure` to determine whether a pipeline should continue running when a job fails. -If `stage` is not defined, the job uses the `test` stage by default. +- 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 (**{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](../jobs/job_control.md#create-a-job-that-must-be-run-manually). +- `false` for manual jobs that also use [`rules`](#rules). +- `false` in all other cases. **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: An array including any number of stage names. Stage names can be: +**Possible inputs**: -- The [default stages](#stages). -- User-defined stages. +- `true` or `false`. -**Example of `stage`**: +**Example of `allow_failure`**: ```yaml -stages: - - build - - test - - deploy - job1: - stage: build + stage: test script: - - echo "This job compiles code." + - execute_script_1 job2: stage: test script: - - echo "This job tests the compiled code. It runs when the build stage completes." + - execute_script_2 + allow_failure: true job3: - script: - - echo "This job also runs in the test stage". - -job4: stage: deploy script: - - echo "This job deploys the code. It runs when the test stage completes." + - deploy_to_staging ``` -**Additional details**: +In this example, `job1` and `job2` run in parallel: -- Jobs can run in parallel if they run on different runners. -- If you have only one runner, jobs can run in parallel if the runner's - [`concurrent` setting](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section) - is greater than `1`. +- If `job1` fails, jobs in the `deploy` stage do not start. +- If `job2` fails, jobs in the `deploy` stage can still start. -#### `stage: .pre` +**Additional details**: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4. +- You can use `allow_failure` as a subkey of [`rules`](#rulesallow_failure). +- You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs). + A blocked pipeline does not run any jobs in later stages until the manual job + is started and completes successfully. -Use the `.pre` stage to make a job run at the start of a pipeline. `.pre` is -always the first stage in a pipeline. User-defined stages execute after `.pre`. -You do not have to define `.pre` in [`stages`](#stages). +#### `allow_failure:exit_codes` -You must have a job in at least one stage other than `.pre` or `.post`. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) in GitLab 13.9. -**Keyword type**: You can only use it with a job's `stage` keyword. +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. -**Example of `stage: .pre`**: +**Keyword type**: Job keyword. You can use it only as part of a job. -```yaml -stages: - - build - - test +**Possible inputs**: -job1: - stage: build - script: - - echo "This job runs in the build stage." +- A single exit code. +- An array of exit codes. -first-job: - stage: .pre +**Example of `allow_failure`**: + +```yaml +test_job_1: script: - - echo "This job runs in the .pre stage, before all other stages." + - echo "Run a script that results in exit code 1. This job fails." + - exit 1 + allow_failure: + exit_codes: 137 -job2: - stage: test +test_job_2: script: - - echo "This job runs in the test stage." + - echo "Run a script that results in exit code 137. This job is allowed to fail." + - exit 137 + allow_failure: + exit_codes: + - 137 + - 255 ``` -#### `stage: .post` - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4. - -Use the `.post` stage to make a job run at the end of a pipeline. `.post` -is always the last stage in a pipeline. User-defined stages execute before `.post`. -You do not have to define `.post` in [`stages`](#stages). - -You must have a job in at least one stage other than `.pre` or `.post`. - -**Keyword type**: You can only use it with a job's `stage` keyword. - -**Example of `stage: .post`**: - -```yaml -stages: - - build - - test - -job1: - stage: build - script: - - echo "This job runs in the build stage." +### `artifacts` -last-job: - stage: .post - script: - - echo "This job runs in the .post stage, after all other stages." +Use `artifacts` to specify which files to save as [job artifacts](../pipelines/job_artifacts.md). +Job artifacts are a list of files and directories that are +attached to the job when it [succeeds, fails, or always](#artifactswhen). -job2: - stage: test - script: - - echo "This job runs in the test stage." -``` +The artifacts are sent to GitLab after the job finishes. They are +available for download in the GitLab UI if the size is smaller than the +the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd). -### `extends` +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`](#dependencies). -Use `extends` to reuse configuration sections. It's an alternative to [YAML anchors](yaml_optimization.md#anchors) -and is a little more flexible and readable. +When using the [`needs`](#needs) keyword, jobs can only download +artifacts from the jobs defined in the `needs` configuration. -**Keyword type**: Job keyword. You can use it only as part of a job. +Job artifacts are only collected for successful jobs by default, and +artifacts are restored after [caches](#cache). -**Possible inputs:** +[Read more about artifacts](../pipelines/job_artifacts.md). -- The name of another job in the pipeline. -- A list (array) of names of other jobs in the pipeline. +#### `artifacts:exclude` -**Example of `extends`:** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) in GitLab 13.1 +> - Requires GitLab Runner 13.1 -```yaml -.tests: - script: rake test - stage: test - only: - refs: - - branches +Use `artifacts:exclude` to prevent files from being added to an artifacts archive. -rspec: - extends: .tests - script: rake rspec - only: - variables: - - $RSPEC -``` +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -In this example, the `rspec` job uses the configuration from the `.tests` template job. -When creating the pipeline, GitLab: +**Possible inputs**: -- 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. +- An array of file paths, relative to the project directory. +- You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) or + [`doublestar.PathMatch`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#PathMatch) patterns. -The result is this `rspec` job: +**Example of `artifacts:exclude`**: ```yaml -rspec: - script: rake rspec - stage: test - only: - refs: - - branches - variables: - - $RSPEC +artifacts: + paths: + - binaries/ + exclude: + - binaries/**/*.o ``` -**Additional details:** +This example stores all files in `binaries/`, but not `*.o` files located in +subdirectories of `binaries/`. -- In GitLab 12.0 and later, you can use multiple parents for `extends`. -- The `extends` keyword supports up to eleven levels of inheritance, but you should - avoid using more than three levels. -- In the example above, `.tests` is a [hidden job](../jobs/index.md#hide-jobs), - but you can extend configuration from regular jobs as well. +**Additional details**: -**Related topics:** +- `artifacts:exclude` paths are not searched recursively. +- Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded using + `artifacts:exclude` too. -- [Reuse configuration sections by using `extends`](yaml_optimization.md#use-extends-to-reuse-configuration-sections). -- Use `extends` to reuse configuration from [included configuration files](yaml_optimization.md#use-extends-and-include-together). - -### `rules` +**Related topics**: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3. +- [Exclude files from job artifacts](../pipelines/job_artifacts.md#exclude-files-from-job-artifacts). -Use `rules` to include or exclude jobs in pipelines. +#### `artifacts:expire_in` -Rules are evaluated when the pipeline is created, and evaluated *in order* -until the first match. When a match is found, the job is either included or excluded from the pipeline, -depending on the configuration. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0 behind a disabled feature flag, the latest job artifacts are kept regardless of expiry time. +> - [Made default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8, keeping latest job artifacts can be disabled at the project level. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276583) in GitLab 13.9, keeping latest job artifacts can be disabled instance-wide. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321323) in GitLab 13.12, the latest pipeline artifacts are kept regardless of expiry time. -You cannot use dotenv variables created in job scripts in rules, because rules are evaluated before any jobs run. +Use `expire_in` to specify how long [job artifacts](../pipelines/job_artifacts.md) are stored before +they expire and are deleted. The `expire_in` setting does not affect: -`rules` replaces [`only/except`](#only--except) and they can't be used together -in the same job. If you configure one job to use both keywords, the GitLab returns -a `key may not be used with rules` error. +- Artifacts from the latest job, unless keeping the latest job artifacts is: + - [Disabled at the project level](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). + - [Disabled instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). +- [Pipeline artifacts](../pipelines/pipeline_artifacts.md). You can't specify an expiration date for + pipeline artifacts. See [When pipeline artifacts are deleted](../pipelines/pipeline_artifacts.md#when-pipeline-artifacts-are-deleted) + for more information. -`rules` accepts an array of rules defined with: +After their expiry, artifacts are deleted hourly by default (using a cron job), and are not +accessible anymore. -- `if` -- `changes` -- `exists` -- `allow_failure` -- `variables` -- `when` +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -You can combine multiple keywords together for [complex rules](../jobs/job_control.md#complex-rules). +**Possible inputs**: The expiry time. If no unit is provided, the time is in seconds. +Valid values include: -The job is added to the pipeline: +- `'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` -- If an `if`, `changes`, or `exists` rule matches and also has `when: on_success` (default), - `when: delayed`, or `when: always`. -- If a rule is reached that is only `when: on_success`, `when: delayed`, or `when: always`. +**Example of `artifacts:expire_in`**: -The job is not added to the pipeline: +```yaml +job: + artifacts: + expire_in: 1 week +``` -- If no rules match. -- If a rule matches and has `when: never`. +**Additional details**: -You can use [`!reference` tags](yaml_optimization.md#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs) -in different jobs. +- 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](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration). +- To override the expiration date and protect artifacts from being automatically deleted: + - Select **Keep** on the job page. + - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of + `expire_in` to `never`. -#### `rules:if` +#### `artifacts:expose_as` -Use `rules:if` clauses to specify when to add a job to a pipeline: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5. -- 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 no `if` statements are true, do not add the job to the pipeline. +Use the `artifacts:expose_as` keyword to +[expose job artifacts in the merge request UI](../pipelines/job_artifacts.md#expose-job-artifacts-in-the-merge-request-ui). -`if:` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md) -or [custom CI/CD variables](../variables/index.md#custom-cicd-variables). +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -**Keyword type**: Job-specific and pipeline-specific. You can use it as part of a job -to configure the job behavior, or with [`workflow`](#workflow) to configure the pipeline behavior. +**Possible inputs**: -**Possible inputs**: A [CI/CD variable expression](../jobs/job_control.md#cicd-variable-expressions). +- The name to display in the merge request UI for the artifacts download link. + Must be combined with [`artifacts:paths`](#artifactspaths). -**Example of `rules:if`**: +**Example of `artifacts:expose_as`**: ```yaml -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' +test: + script: ["echo 'test' > file.txt"] + artifacts: + expose_as: 'artifact 1' + paths: ['file.txt'] ``` **Additional 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 define `when` once per rule, or once at the job-level, which applies to - all rules. You can't mix `when` at the job-level with `when` in rules. -- Unlike variables in [`script`](../variables/index.md#use-cicd-variables-in-job-scripts) - sections, variables in rules expressions are always formatted as `$VARIABLE`. - - You can use `rules:if` with `include` to [conditionally include other configuration files](includes.md#use-rules-with-include). +- If `artifacts:paths` uses [CI/CD variables](../variables/index.md), the artifacts do not display in the UI. +- A maximum of 10 job artifacts per merge request can be exposed. +- Glob patterns are unsupported. +- If a directory is specified and there is more than one file in the directory, + the link is to the job [artifacts browser](../pipelines/job_artifacts.md#download-job-artifacts). +- If [GitLab Pages](../../administration/pages/index.md) is enabled, GitLab automatically + renders the artifacts when the artifacts is a single file with one of these extensions: + - `.html` or `.htm` + - `.txt` + - `.json` + - `.xml` + - `.log` **Related topics**: -- [Common `if` expressions for `rules`](../jobs/job_control.md#common-if-clauses-for-rules). -- [Avoid duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines). - -#### `rules:changes` - -Use `rules:changes` to specify when to add a job to a pipeline by checking for changes -to specific files. - -WARNING: -You should use `rules: changes` only with **branch pipelines** or **merge request pipelines**. -You can use `rules: changes` with other pipeline types, but `rules: changes` always -evaluates to true when there is no Git `push` event. Tag pipelines, scheduled pipelines, -and so on do **not** have a Git `push` event associated with them. A `rules: changes` job -is **always** added to those pipelines if there is no `if:` that limits the job to -branch or merge request pipelines. - -**Keyword type**: Job keyword. You can use it only as part of a job. - -**Possible inputs**: An array of file paths. In GitLab 13.6 and later, -[file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges). - -**Example of `rules:changes`**: - -```yaml -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 -``` +- [Expose job artifacts in the merge request UI](../pipelines/job_artifacts.md#expose-job-artifacts-in-the-merge-request-ui). -- If the pipeline is a merge request pipeline, check `Dockerfile` 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 `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`). +#### `artifacts:name` -**Additional details**: +Use the `artifacts:name` keyword to define the name of the created artifacts +archive. You can specify a unique name for every archive. -- `rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychanges--exceptchanges). -- You can use `when: never` to implement a rule similar to [`except:changes`](#onlychanges--exceptchanges). -- `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). - -#### `rules:exists` +If not defined, the default name is `artifacts`, which becomes `artifacts.zip` when downloaded. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -Use `exists` to run a job when certain files exist in the repository. +**Possible inputs**: -**Keyword type**: Job keyword. You can use it only as part of a job. +- The name of the artifacts archive. Can use [CI/CD variables](../variables/index.md). Must be combined with + [`artifacts:paths`](#artifactspaths). -**Possible inputs**: An array of file paths. Paths are relative to the project directory (`$CI_PROJECT_DIR`) -and can't directly link outside it. File paths can use glob patterns. +**Example of `artifacts:name`**: -**Example of `rules:exists`**: +To create an archive with a name of the current job: ```yaml job: - script: docker build -t my-image:$CI_COMMIT_REF_SLUG . - rules: - - exists: - - Dockerfile + artifacts: + name: "job1-artifacts-file" + paths: + - binaries/ ``` -`job` runs if a `Dockerfile` exists anywhere in the repository. - -**Additional details**: - -- Glob patterns are interpreted with Ruby [`File.fnmatch`](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch) - with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. -- For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns or - file paths. After the 10,000th check, rules with patterned globs always match. - In other words, the `exists` rule always assumes a match in projects with more - than 10,000 files. -- `exists` resolves to `true` if any of the listed files are found (an `OR` operation). +**Related topics**: -#### `rules:allow_failure` +- [Use CI/CD variables to define the artifacts name](../pipelines/job_artifacts.md#use-cicd-variables-to-define-the-artifacts-name). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8. +#### `artifacts:paths` -Use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail -without stopping the pipeline. +Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly +link outside it. -You can also use `allow_failure: true` with a manual job. The pipeline continues -running without waiting for the result of the manual job. `allow_failure: false` -combined with `when: manual` in rules causes the pipeline to wait for the manual -job to run before continuing. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -**Keyword type**: Job keyword. You can use it only as part of a job. +**Possible inputs**: -**Possible inputs**: `true` or `false`. Defaults to `false` if not defined. +- An array of file paths, relative to the project directory. +- You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) + patterns and: + - In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620), + [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). + - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). -**Example of `rules:allow_failure`**: +**Example of `artifacts:paths`**: ```yaml job: - script: echo "Hello, Rules!" - rules: - - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH' - when: manual - allow_failure: true + artifacts: + paths: + - binaries/ + - .config ``` -If the rule matches, then the job is a manual job with `allow_failure: true`. +This example creates an artifact with `.config` and all the files in the `binaries` directory. **Additional details**: -- The rule-level `rules:allow_failure` overrides the job-level [`allow_failure`](#allow_failure), - and only applies when the specific rule triggers the job. - -#### `rules:variables` +- If not used with [`artifacts:name`](#artifactsname) defined, the artifacts file + is named `artifacts`, which becomes `artifacts.zip` when downloaded. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209864) in GitLab 13.7. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289803) in GitLab 13.10. +**Related topics**: -Use [`variables`](#variables) in `rules:` to define variables for specific conditions. +- To restrict which jobs a specific job fetches artifacts from, see [`dependencies`](#dependencies). +- [Create job artifacts](../pipelines/job_artifacts.md#create-job-artifacts). -**Keyword type**: Job-specific. You can use it only as part of a job. - -**Possible inputs**: A hash of variables in the format `VARIABLE-NAME: value`. +#### `artifacts:public` -**Example of `rules:variables`**: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49775) in GitLab 13.8 +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's recommended for production use. -```yaml -job: - variables: - DEPLOY_VARIABLE: "default-deploy" - rules: - - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH - variables: # Override DEPLOY_VARIABLE defined - DEPLOY_VARIABLE: "deploy-production" # at the job level. - - if: $CI_COMMIT_REF_NAME =~ /feature/ - variables: - IS_A_FEATURE: "true" # Define a new variable. - script: - - echo "Run script with $DEPLOY_VARIABLE as an argument" - - echo "Run another script if $IS_A_FEATURE exists" -``` +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `non_public_artifacts`. On +GitLab.com, this feature is not available. -### `only` / `except` +Use `artifacts:public` to determine whether the job artifacts should be +publicly available. -NOTE: -`only` and `except` are not being actively developed. [`rules`](#rules) is the preferred -keyword to control when to add jobs to pipelines. +When `artifacts:public` is `true` (default), the artifacts in +public pipelines are available for download by anonymous and guest users. -You can use `only` and `except` to control when to add jobs to pipelines. +To deny read access for anonymous and guest users to artifacts in public +pipelines, set `artifacts:public` to `false`: -- Use `only` to define when a job runs. -- Use `except` to define when a job **does not** run. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -Four keywords can be used with `only` and `except`: +**Possible inputs**: -- [`refs`](#onlyrefs--exceptrefs) -- [`variables`](#onlyvariables--exceptvariables) -- [`changes`](#onlychanges--exceptchanges) -- [`kubernetes`](#onlykubernetes--exceptkubernetes) +- `true` (default if not defined) or `false`. -See [specify when jobs run with `only` and `except`](../jobs/job_control.md#specify-when-jobs-run-with-only-and-except) -for more details and examples. +**Example of `artifacts:paths`**: -#### `only:refs` / `except:refs` +```yaml +job: + artifacts: + public: false +``` -Use the `only:refs` and `except:refs` keywords to control when to add jobs to a -pipeline based on branch names or pipeline types. +#### `artifacts:reports` -**Keyword type**: Job keyword. You can use it only as part of a job. +Use [`artifacts:reports`](artifacts_reports.md) to collect artifacts generated by +included templates in jobs. -**Possible inputs**: An array including any number of: +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -- Branch names, for example `main` or `my-feature-branch`. -- [Regular expressions](../jobs/job_control.md#only--except-regex-syntax) - that match against branch names, for example `/^feature-.*/`. -- The following keywords: +**Possible inputs**: - | **Value** | **Description** | - | -------------------------|-----------------| - | `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | - | `branches` | When the Git reference for a pipeline is a branch. | - | `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. | - | `external` | When you use CI services other than GitLab. | - | `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). | - | `merge_requests` | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../pipelines/merge_request_pipelines.md), [merged results pipelines](../pipelines/pipelines_for_merged_results.md), and [merge trains](../pipelines/merge_trains.md). | - | `pipelines` | For [multi-project pipelines](../pipelines/multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../pipelines/multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](#trigger) keyword. | - | `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. | - | `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | - | `tags` | When the Git reference for a pipeline is a tag. | - | `triggers` | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). | - | `web` | For pipelines created by selecting **Run pipeline** in the GitLab UI, from the project's **CI/CD > Pipelines** section. | +- See list of available [artifacts reports types](artifacts_reports.md). -**Example of `only:refs` and `except:refs`**: +**Example of `artifacts:reports`**: ```yaml -job1: - script: echo - only: - - main - - /^issue-.*$/ - - merge_requests - -job2: - script: echo - except: - - main - - /^stable-branch.*$/ - - schedules +rspec: + stage: test + script: + - bundle install + - rspec --format RspecJunitFormatter --out rspec.xml + artifacts: + reports: + junit: rspec.xml ``` -**Additional details:** - -- Scheduled pipelines run on specific branches, so jobs configured with `only: branches` - run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches` - from running on scheduled pipelines. -- `only` or `except` used without any other keywords are equivalent to `only: refs` - or `except: refs`. For example, the following two jobs configurations have the same - behavior: - - ```yaml - job1: - script: echo - only: - - branches - - job2: - script: echo - only: - refs: - - branches - ``` - -- If a job does not use `only`, `except`, or [`rules`](#rules), then `only` is set to `branches` - and `tags` by default. +**Additional details**: - For example, `job1` and `job2` are equivalent: +- Combining reports in parent pipelines using [artifacts from child pipelines](#needspipelinejob) is + not supported. Track progress on adding support in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215725). +- To be able to browse the report output files, include the [`artifacts:paths`](#artifactspaths) keyword. Please note that this will upload and store the artifact twice. +- The test reports are collected regardless of the job results (success or failure). + You can use [`artifacts:expire_in`](#artifactsexpire_in) to set up an expiration + date for artifacts reports. - ```yaml - job1: - script: echo 'test' +#### `artifacts:untracked` - job2: - script: echo 'test' - only: - - branches - - tags - ``` +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` file. -#### `only:variables` / `except:variables` +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -Use the `only:variables` or `except:variables` keywords to control when to add jobs -to a pipeline, based on the status of [CI/CD variables](../variables/index.md). +**Possible inputs**: -**Keyword type**: Job keyword. You can use it only as part of a job. +- `true` or `false` (default if not defined). -**Possible inputs**: An array of [CI/CD variable expressions](../jobs/job_control.md#cicd-variable-expressions). +**Example of `artifacts:untracked`**: -**Example of `only:variables`**: +Save all Git untracked files: ```yaml -deploy: - script: cap staging deploy - only: - variables: - - $RELEASE == "staging" - - $STAGING +job: + artifacts: + untracked: true ``` **Related topics**: -- [`only:variables` and `except:variables` examples](../jobs/job_control.md#only-variables--except-variables-examples). - -#### `only:changes` / `except:changes` +- [Add untracked files to artifacts](../pipelines/job_artifacts.md#add-untracked-files-to-artifacts). -Use the `changes` keyword with `only` to run a job, or with `except` to skip a job, -when a Git push event modifies a file. - -Use `changes` in pipelines with the following refs: +#### `artifacts:when` -- `branches` -- `external_pull_requests` -- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests)) +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. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -**Possible inputs**: An array including any number of: +**Possible inputs**: -- Paths to files. -- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory - and all its subdirectories, for example `path/to/directory/**/*`. -- Wildcard ([glob](https://en.wikipedia.org/wiki/Glob_(programming))) 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"`. +- `on_success` (default): Upload artifacts only when the job succeeds. +- `on_failure`: Upload artifacts only when the job fails. +- `always`: Always upload artifacts. For example, when + [uploading artifacts](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab) + required to troubleshoot failing tests. -**Example of `only:changes`**: +**Example of `artifacts:when`**: ```yaml -docker build: - script: docker build -t my-image:$CI_COMMIT_REF_SLUG . - only: - refs: - - branches - changes: - - Dockerfile - - docker/scripts/* - - dockerfiles/**/* - - more_scripts/*.{rb,py,sh} - - "**/*.json" +job: + artifacts: + when: on_failure ``` -**Additional details**: - -- `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). -- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`, - `changes` can't determine if a given file is new or old and always returns `true`. -- If you use `only: changes` with other refs, jobs ignore the changes and always run. -- If you use `except: changes` with other refs, jobs ignore the changes and never run. - -**Related topics**: +### `before_script` -- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples). -- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), - you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests). -- Use `changes` with [new branches or tags *without* pipelines for merge requests](../jobs/job_control.md#use-onlychanges-without-pipelines-for-merge-requests). -- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines). - -#### `only:kubernetes` / `except:kubernetes` +Use `before_script` to define an array of commands that should run before each job's +`script` commands, but after [artifacts](#artifacts) are restored. -Use `only:kubernetes` or `except:kubernetes` to control if jobs are added to the pipeline -when the Kubernetes service is active in the project. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -**Keyword type**: Job-specific. You can use it only as part of a job. +**Possible inputs**: An array including: -**Possible inputs**: The `kubernetes` strategy accepts only the `active` keyword. +- Single line commands. +- Long commands [split over multiple lines](script.md#split-long-commands). +- [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). -**Example of `only:kubernetes`**: +**Example of `before_script`**: ```yaml -deploy: - only: - kubernetes: active +job: + before_script: + - echo "Execute this command before any 'script:' commands." + script: + - echo "This command executes after the job's 'before_script' commands." ``` -In this example, the `deploy` job runs only when the Kubernetes service is active -in the project. - -### `needs` - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) in GitLab 12.2. -> - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) in GitLab 12.8, `needs: []` lets jobs start immediately. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) in GitLab 14.2, you can refer to jobs in the same stage as the job you are configuring. +**Additional details**: -Use `needs:` to execute jobs out-of-order. Relationships between jobs -that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md). +- Scripts you specify in `before_script` are concatenated with any scripts you specify + in the main [`script`](#script). The combined scripts execute together in a single shell. -You can ignore stage ordering and run some jobs without waiting for others to complete. -Jobs in multiple stages can run concurrently. +**Related topics**: -**Keyword type**: Job keyword. You can use it only as part of a job. +- [Use `before_script` with `default`](script.md#set-a-default-before_script-or-after_script-for-all-jobs) + to define a default array of commands that should run before the `script` commands in all jobs. +- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes). +- [Use color codes with `before_script`](script.md#add-color-codes-to-script-output) + to make job logs easier to review. +- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) + to simplify job log output. -**Possible inputs**: +### `cache` -- An array of jobs. -- An empty array (`[]`), to set the job to start as soon as the pipeline is created. +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. -**Example of `needs`**: +Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts). -```yaml -linux:build: - stage: build - script: echo "Building linux..." +Learn more about caches in [Caching in GitLab CI/CD](../caching/index.md). -mac:build: - stage: build - script: echo "Building mac..." +#### `cache:paths` -lint: - stage: test - needs: [] - script: echo "Linting..." +Use the `cache:paths` keyword to choose which files or directories to cache. -linux:rspec: - stage: test - needs: ["linux:build"] - script: echo "Running rspec on linux..." +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -mac:rspec: - stage: test - needs: ["mac:build"] - script: echo "Running rspec on mac..." +**Possible inputs**: -production: - stage: deploy - script: echo "Running production..." -``` +- An array of paths relative to the project directory (`$CI_PROJECT_DIR`). + You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) + patterns: + - In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620), + [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). + - In GitLab Runner 12.10 and earlier, + [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). -This example creates four paths of execution: +**Example of `cache:paths`**: -- Linter: The `lint` job runs immediately without waiting for the `build` stage - to complete because it has no needs (`needs: []`). -- Linux path: The `linux:rspec` job runs as soon as the `linux:build` - job finishes, without waiting for `mac:build` to finish. -- macOS path: The `mac:rspec` jobs runs as soon as the `mac:build` - job finishes, without waiting for `linux:build` to finish. -- The `production` job runs as soon as all previous jobs finish: - `linux:build`, `linux:rspec`, `mac:build`, `mac:rspec`. +Cache all files in `binaries` that end in `.apk` and the `.config` file: -**Additional details**: +```yaml +rspec: + script: + - echo "This job uses a cache." + cache: + key: binaries-cache + paths: + - binaries/*.apk + - .config +``` -- 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 our - [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). - - For self-managed instances, the default limit is 50. This limit [can be changed](../../administration/cicd.md#set-the-needs-job-limit). -- If `needs:` refers to a job that uses the [`parallel`](#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. -- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you - can refer to jobs in the same stage as the job you are configuring. This feature is - enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) - this feature is available by default. -- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. Stages must be - explicitly defined for all jobs that use the `needs:` keyword, or are referenced - in a job's `needs:` section. -- In GitLab 13.9 and older, 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. +**Related topics**: -#### `needs:artifacts` +- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more + `cache:paths` examples. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.6. +#### `cache:key` -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 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. -Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are -downloaded in jobs that use `needs`. +If not set, the default key is `default`. All jobs with the `cache` keyword but +no `cache:key` share the `default` cache. -**Keyword type**: Job keyword. You can use it only as part of a job. Must be used with `needs:job`. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). **Possible inputs**: -- `true` (default) or `false`. +- A string. +- A [predefined variables](../variables/index.md). +- A combination of both. -**Example of `needs:artifacts`**: +**Example of `cache:key`**: ```yaml -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 +cache-job: + script: + - echo "This job uses a cache." + cache: + key: binaries-cache-$CI_COMMIT_REF_SLUG + paths: + - binaries/ ``` -In this example: +**Additional details**: -- 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. +- 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: -**Additional details**: + - The `/` character, or the equivalent URI-encoded `%2F`. + - Only the `.` character (any number), or the equivalent URI-encoded `%2E`. -- In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword - with `needs`. +- 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. -#### `needs:project` **(PREMIUM)** +**Related topics**: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.7. +- You can specify a [fallback cache key](../caching/index.md#use-a-fallback-cache-key) + to use if the specified `cache:key` is not found. +- You can [use multiple cache keys](../caching/index.md#use-multiple-caches) in a single job. +- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more + `cache:key` examples. -Use `needs:project` to download artifacts from up to five jobs in other pipelines. -The artifacts are downloaded from the latest successful pipeline for the specified ref. +##### `cache:key:files` -If there is a pipeline running for the specified ref, a job with `needs:project` -does not wait for the pipeline to complete. Instead, the job downloads the artifact -from the latest pipeline that completed successfully. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. -`needs:project` must be used with `job:`, `ref:`, and `artifacts:`. +Use the `cache:key:files` keyword to generate a new key when one or two specific files +change. `cache:key:files` lets you reuse some caches, and rebuild them less often, +which speeds up subsequent pipeline runs. -**Keyword type**: Job keyword. You can use it only as part of a job. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). **Possible inputs**: -- `needs:project`: 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`. -- `job`: The job to download artifacts from. -- `ref`: The ref to download artifacts from. -- `artifacts`: Must be `true` to download artifacts. +- An array of one or two file paths. -**Examples of `needs:project`**: +**Example of `cache:key:files`**: ```yaml -build_job: - stage: build +cache-job: script: - - ls -lhR - needs: - - project: namespace/group/project-name - job: build-1 - ref: main - artifacts: true + - echo "This job uses a cache." + cache: + key: + files: + - Gemfile.lock + - package.json + paths: + - vendor/ruby + - node_modules ``` -In this example, `build_job` downloads the artifacts from the latest successful `build-1` job -on the `main` branch in the `group/project-name` project. - -In GitLab 13.3 and later, you can use [CI/CD variables](../variables/index.md) in `needs:project`, -for example: - -```yaml -build_job: - stage: build - script: - - ls -lhR - needs: - - project: $CI_PROJECT_PATH - job: $DEPENDENCY_JOB_NAME - ref: $ARTIFACTS_DOWNLOAD_REF - artifacts: true -``` +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**: -- 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 at least the Reporter 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`](#trigger). -- When using `needs:project` to download artifacts from another pipeline, the job does not wait for - the needed job to complete. [Directed acyclic graph](../directed_acyclic_graph/index.md) - behavior 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:`](#parallel). -- Support for [CI/CD variables](../variables/index.md) in `project`, `job`, and `ref` was - [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202093) in GitLab 13.3. - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235761) in GitLab 13.4. - -**Related topics**: - -- To download artifacts between [parent-child pipelines](../pipelines/parent_child_pipelines.md), - use [`needs:pipeline:job`](#needspipelinejob). +- The cache `key` is a SHA computed from the most recent commits +that changed each listed file. + If neither file is changed in any commits, the fallback key is `default`. -#### `needs:pipeline:job` +##### `cache:key:prefix` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. -A [child pipeline](../pipelines/parent_child_pipelines.md) can download artifacts from a job in -its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy. +Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles). -**Keyword type**: Job keyword. You can use it only as part of a job. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). **Possible inputs**: -- `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`): - - ```yaml - create-artifact: - stage: build - script: echo 'sample artifact' > artifact.txt - artifacts: - paths: [artifact.txt] - - child-pipeline: - stage: test - trigger: - include: child.yml - strategy: depend - variables: - PARENT_PIPELINE_ID: $CI_PIPELINE_ID - ``` +- A string +- A [predefined variables](../variables/index.md) +- A combination of both. -- Child pipeline (`child.yml`): +**Example of `cache:key:prefix`**: - ```yaml - use-artifact: - script: cat artifact.txt - needs: - - pipeline: $PARENT_PIPELINE_ID - job: create-artifact - ``` +```yaml +rspec: + script: + - echo "This rspec job uses a cache." + cache: + key: + files: + - Gemfile.lock + prefix: $CI_JOB_NAME + paths: + - vendor/ruby +``` -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. +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**: -- 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`](#needsartifacts). - -#### `needs:optional` - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30680) in GitLab 13.10. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323891) in GitLab 14.0. - -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. +- If no file in `cache:key:files` is changed in any commits, the prefix is added to the `default` key. -Jobs that use [`rules`](#rules), [`only`, or `except`](#only--except), might -not always exist in a pipeline. When the pipeline is created, GitLab checks the `needs` -relationships before starting it. Without `optional: true`, needs relationships that -point to a job that does not exist stops the pipeline from starting and causes a pipeline -error similar to: +#### `cache:untracked` -- `'job1' job needs 'job2' job, but it was not added to the pipeline` +Use `untracked: true` to cache all files that are untracked in your Git repository: -**Keyword type**: Job keyword. You can use it only as part of a job. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). **Possible inputs**: -- `job:`: The job to make optional. - `true` or `false` (default). -**Example of `needs:optional`**: +**Example of `cache:untracked`**: ```yaml -build: - stage: build - rules: - - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH - rspec: - stage: test - needs: - - job: build - optional: true + script: test + cache: + untracked: true ``` -In this example: +**Additional details**: -- When the branch is the default branch, the `build` job exists in the pipeline, and the `rspec` - job waits for it to complete before starting. -- When the branch is not the default branch, the `build` job does not exist in the pipeline. - The `rspec` job runs immediately (similar to `needs: []`) because its `needs` - relationship to the `build` job is optional. +- You can combine `cache:untracked` with `cache:paths` to cache all untracked files + as well as files in the configured paths. For example: -#### `needs:pipeline` + ```yaml + rspec: + script: test + cache: + untracked: true + paths: + - binaries/ + ``` -You can mirror the pipeline status from an upstream pipeline to a bridge job by -using the `needs:pipeline` keyword. The latest pipeline status from the default branch is -replicated to the bridge job. +#### `cache:when` -**Keyword type**: Job keyword. You can use it only as part of a job. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18969) in GitLab 13.5 and GitLab Runner v13.5.0. + +Use `cache:when` to define when to save the cache, based on the status of the job. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). **Possible inputs**: -- 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`. +- `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 `needs:pipeline`**: +**Example of `cache:when`**: ```yaml -upstream_bridge: - stage: test - needs: - pipeline: other/project +rspec: + script: rspec + cache: + paths: + - rspec/ + when: 'always' ``` -**Additional details**: +This example stores the cache whether or not the job fails or succeeds. -- If you add the `job` keyword to `needs:pipeline`, the job no longer mirrors the - pipeline status. The behavior changes to [`needs:pipeline:job`](#needspipelinejob). +#### `cache:policy` -### `tags` +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). -> - A limit of 50 tags per job [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338929) in GitLab 14.3. -> - A limit of 50 tags per job [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/339855) in GitLab 14.3. +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`. -Use `tags` to select a specific runner from the list of all runners that are -available for the project. +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`. -When you register a runner, you can specify the runner's tags, for -example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner must -be assigned every tag listed in the job. +Use the `pull` policy when you have many jobs executing in parallel that use the same cache. +This policy speeds up job execution and reduces load on the cache server. You can +use a job with the `push` policy to build the cache. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: -- An array of tag names. -- [CI/CD variables](../runners/configure_runners.md#use-cicd-variables-in-tags) in GitLab 14.1 and later. +- `pull` +- `push` +- `pull-push` (default) -**Example of `tags`**: +**Example of `cache:policy`**: ```yaml -job: - tags: - - ruby - - postgres +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..." ``` -In this example, only runners with *both* the `ruby` and `postgres` tags can run the job. +### `coverage` -**Additional details**: +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. -- In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later, - the number of tags must be less than `50`. +To extract the code coverage value in the matching line, GitLab uses this +regular expression: `\d+(\.\d+)?`. -**Related topics**: +**Possible inputs**: -- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run). +- A regular expression. Must start and end with `/`. -### `allow_failure` +**Example of `coverage`**: -Use `allow_failure` to determine whether a pipeline should continue running when a job fails. +```yaml +job1: + script: rspec + coverage: '/Code coverage: \d+\.\d+/' +``` -- To let the pipeline continue running subsequent jobs, use `allow_failure: true`. -- To stop the pipeline from running subsequent jobs, use `allow_failure: false`. +In this example: -When jobs are allowed to fail (`allow_failure: true`) an orange warning (**{status_warning}**) -indicates that a job failed. However, the pipeline is successful and the associated commit -is marked as passed with no warnings. +1. GitLab checks the job log for a line that matches the regular expression. A line + like `Code coverage: 67.89` would match. +1. GitLab then checks the line to find a match to `\d+(\.\d+)?`. The sample matching + line above gives a code coverage of `67.89`. -This same warning is displayed when: +**Additional details**: -- All other jobs in the stage are successful. -- All other jobs in the pipeline are successful. +- If there is more than one matched line in the job output, the last line is used. +- Leading zeros are removed. +- Coverage output from [child pipelines](../pipelines/parent_child_pipelines.md) + is not recorded or displayed. Check [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/280818) + for more details. -The default value for `allow_failure` is: +### `dast_configuration` **(ULTIMATE)** -- `true` for [manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually). -- `false` for manual jobs that also use [`rules`](#rules). -- `false` in all other cases. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5981) in GitLab 14.1. -**Keyword type**: Job keyword. You can use it only as part of a job. +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`. -**Possible inputs**: `true` or `false`. +**Keyword type**: Job keyword. You can use only as part of a job. -**Example of `allow_failure`**: +**Possible inputs**: 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`**: ```yaml -job1: - stage: test - script: - - execute_script_1 +stages: + - build + - dast -job2: - stage: test - script: - - execute_script_2 - allow_failure: true +include: + - template: DAST.gitlab-ci.yml -job3: - stage: deploy - script: - - deploy_to_staging +dast: + dast_configuration: + site_profile: "Example Co" + scanner_profile: "Quick Passive Test" ``` -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. +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**: -- You can use `allow_failure` as a subkey of [`rules:`](#rulesallow_failure). -- You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs). - A blocked pipeline does not run any jobs in later stages until the manual job - is started and completes successfully. - -#### `allow_failure:exit_codes` - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) in GitLab 13.9. - -Use `allow_failure:exit_codes` to control when a job should be -allowed to fail. The job is `allow_failure: true` for any of the listed exit codes, -and `allow_failure` false for any other exit code. - -**Keyword type**: Job keyword. You can use it only as part of a job. - -**Possible inputs**: - -- A single exit code. -- An array of exit codes. +- Settings contained in either a site profile or scanner profile take precedence over those + contained in the DAST template. -**Example of `allow_failure`**: +**Related topics**: -```yaml -test_job_1: - script: - - echo "Run a script that results in exit code 1. This job fails." - - exit 1 - allow_failure: - exit_codes: 137 +- [Site profile](../../user/application_security/dast/index.md#site-profile). +- [Scanner profile](../../user/application_security/dast/index.md#scanner-profile). -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 -``` +### `dependencies` -### `when` +Use the `dependencies` keyword to define a list of jobs to fetch [artifacts](#artifacts) from. +You can also set a job to download no artifacts at all. -Use `when` to configure the conditions for when jobs run. If not defined in a job, -the default value is `when: on_success`. +If you do not use `dependencies`, all artifacts from previous stages are passed to each job. **Keyword type**: Job keyword. You can use it only as part of a job. **Possible inputs**: -- `on_success` (default): Run the job only when all jobs in earlier stages succeed - or have `allow_failure: true`. -- `manual`: Run the job only when [triggered manually](../jobs/job_control.md#create-a-job-that-must-be-run-manually). -- `always`: Run the job regardless of the status of jobs in earlier stages. -- `on_failure`: Run the job only when at least one job in an earlier stage fails. -- `delayed`: [Delay the execution of a job](../jobs/job_control.md#run-a-job-after-a-delay) - for a specified duration. -- `never`: Don't run the job. +- The names of jobs to fetch artifacts from. +- An empty array (`[]`), to configure the job to not download any artifacts. -**Example of `when`**: +**Example of `dependencies`**: ```yaml -stages: - - build - - cleanup_build - - test - - deploy - - cleanup +build osx: + stage: build + script: make build:osx + artifacts: + paths: + - binaries/ -build_job: +build linux: stage: build - script: - - make build + script: make build:linux + artifacts: + paths: + - binaries/ -cleanup_build_job: - stage: cleanup_build - script: - - cleanup build when failed - when: on_failure +test osx: + stage: test + script: make test:osx + dependencies: + - build:osx -test_job: +test linux: stage: test - script: - - make test + script: make test:linux + dependencies: + - build:linux -deploy_job: +deploy: stage: deploy - script: - - make deploy - when: manual - -cleanup_job: - stage: cleanup - script: - - cleanup after jobs - when: always + script: make deploy ``` -In this example, the script: +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`. -1. Executes `cleanup_build_job` only when `build_job` fails. -1. Always executes `cleanup_job` as the last step in pipeline regardless of - success or failure. -1. Executes `deploy_job` when you run it manually in the GitLab UI. +The `deploy` job downloads artifacts from all previous jobs because of +the [stage](#stages) precedence. **Additional details**: -- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you - can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and - earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. -- The default behavior of `allow_failure` changes to `true` with `when: manual`. - However, if you use `when: manual` with [`rules`](#rules), `allow_failure` defaults - to `false`. - -**Related topics**: - -- `when` can be used with [`rules`](#rules) for more dynamic job control. -- `when` can be used with [`workflow`](#workflow) to control when a pipeline can start. +- 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](#artifactsexpire_in) or + [deleted](../pipelines/job_artifacts.md#delete-job-artifacts), then the job fails. ### `environment` @@ -1999,23 +1551,19 @@ environment. Use the `action` keyword to specify jobs that prepare, start, or stop environments. -| **Value** | **Description** | -|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `start` | Default value. Indicates that job starts the environment. The deployment is created after the job starts. | -| `prepare` | Indicates that the job is only preparing the environment. It does not trigger deployments. [Read more about preparing environments](../environments/index.md#prepare-an-environment-without-creating-a-deployment). | -| `stop` | Indicates that job stops deployment. See the example below. | +**Keyword type**: Job keyword. You can use it only as part of a job. -Take for instance: +**Possible inputs**: One of the following keywords: -```yaml -review_app: - stage: deploy - script: make deploy-app - environment: - name: review/$CI_COMMIT_REF_SLUG - url: https://$CI_ENVIRONMENT_SLUG.example.com - on_stop: stop_review_app +| **Value** | **Description** | +|:----------|:----------------| +| `start` | Default value. Indicates that the job starts the environment. The deployment is created after the job starts. | +| `prepare` | Indicates that the job is only preparing the environment. It does not trigger deployments. [Read more about preparing environments](../environments/index.md#prepare-an-environment-without-creating-a-deployment). | +| `stop` | Indicates that the job stops a deployment. For more detail, read [Stop an environment](../environments/index.md#stop-an-environment). | + +**Example of `environment:action`**: +```yaml stop_review_app: stage: deploy variables: @@ -2027,39 +1575,6 @@ stop_review_app: action: stop ``` -In the above example, the `review_app` job deploys to the `review` -environment. A new `stop_review_app` job is listed under `on_stop`. -After the `review_app` job is finished, it triggers the -`stop_review_app` job based on what is defined under `when`. In this case, -it is set to `manual`, so it needs a [manual action](../jobs/job_control.md#create-a-job-that-must-be-run-manually) from -the GitLab UI to run. - -Also in the example, `GIT_STRATEGY` is set to `none`. If the -`stop_review_app` job is [automatically triggered](../environments/index.md#stop-an-environment), -the runner won't try to check out the code after the branch is deleted. - -The example also overwrites global variables. If your `stop` `environment` job depends -on global variables, use [anchor variables](yaml_optimization.md#yaml-anchors-for-variables) when you set the `GIT_STRATEGY` -to change the job without overriding the global variables. - -The `stop_review_app` job is **required** to have the following keywords defined: - -- `when`, defined at either: - - [The job level](#when). - - [In a rules clause](#rules). If you use `rules:` and `when: manual`, you should - also set [`allow_failure: true`](#allow_failure) so the pipeline can complete - even if the job doesn't run. -- `environment:name` -- `environment:action` - -Additionally, both jobs should have matching [`rules`](#only--except) -or [`only/except`](#only--except) configuration. - -In the examples above, if the configuration is not identical: - -- The `stop_review_app` job might not be included in all pipelines that include the `review_app` job. -- It is not possible to trigger the `action: stop` to stop the environment automatically. - #### `environment:auto_stop_in` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8. @@ -2185,1211 +1700,869 @@ 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/>. -### `cache` - -Use `cache` to specify a list of files and directories to -cache between jobs. You can only use paths that are in the local working copy. - -Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts). - -Learn more about caches in [Caching in GitLab CI/CD](../caching/index.md). - -#### `cache:paths` - -Use the `cache:paths` keyword to choose which files or directories to cache. +### `extends` -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +Use `extends` to reuse configuration sections. It's an alternative to [YAML anchors](yaml_optimization.md#anchors) +and is a little more flexible and readable. -**Possible inputs**: An array of paths relative to the project directory (`$CI_PROJECT_DIR`). -You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) -patterns: +**Keyword type**: Job keyword. You can use it only as part of a job. -- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620), -[`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). -- In GitLab Runner 12.10 and earlier, -[`filepath.Match`](https://pkg.go.dev/path/filepath#Match). +**Possible inputs**: -**Example of `cache:paths`**: +- The name of another job in the pipeline. +- A list (array) of names of other jobs in the pipeline. -Cache all files in `binaries` that end in `.apk` and the `.config` file: +**Example of `extends`**: ```yaml +.tests: + script: rake test + stage: test + only: + refs: + - branches + rspec: - script: - - echo "This job uses a cache." - cache: - key: binaries-cache - paths: - - binaries/*.apk - - .config + extends: .tests + script: rake rspec + only: + variables: + - $RSPEC ``` -**Related topics**: - -- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) 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. - -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). - -**Possible inputs**: +In this example, the `rspec` job uses the configuration from the `.tests` template job. +When creating the pipeline, GitLab: -- A string. -- A [predefined variables](../variables/index.md). -- A combination of both. +- 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. -**Example of `cache:key`**: +The result is this `rspec` job: ```yaml -cache-job: - script: - - echo "This job uses a cache." - cache: - key: binaries-cache-$CI_COMMIT_REF_SLUG - paths: - - binaries/ +rspec: + script: rake rspec + stage: test + only: + refs: + - branches + variables: + - $RSPEC ``` **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. +- In GitLab 12.0 and later, you can use multiple parents for `extends`. +- The `extends` keyword supports up to eleven levels of inheritance, but you should + avoid using more than three levels. +- In the example above, `.tests` is a [hidden job](../jobs/index.md#hide-jobs), + but you can extend configuration from regular jobs as well. **Related topics**: -- You can specify a [fallback cache key](../caching/index.md#use-a-fallback-cache-key) - to use if the specified `cache:key` is not found. -- You can [use multiple cache keys](../caching/index.md#use-multiple-caches) in a single job. -- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more - `cache:key` examples. - -##### `cache:key:files` - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. - -Use the `cache:key:files` keyword to generate a new key when one or two specific files -change. `cache:key:files` lets you reuse some caches, and rebuild them less often, -which speeds up subsequent pipeline runs. - -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). - -**Possible inputs**: An array of one or two file paths. - -**Example of `cache:key:files`**: - -```yaml -cache-job: - script: - - echo "This job uses a cache." - cache: - key: - files: - - Gemfile.lock - - package.json - paths: - - vendor/ruby - - node_modules -``` - -This example creates a cache for Ruby and Node.js dependencies. The cache -is tied to the current versions of the `Gemfile.lock` and `package.json` files. When one of -these files changes, a new cache key is computed and a new cache is created. Any future -job runs that use the same `Gemfile.lock` and `package.json` with `cache:key:files` -use the new cache, instead of rebuilding the dependencies. - -**Additional details**: - -- The cache `key` is a SHA computed from the most recent commits -that changed each listed file. - If neither file is changed in any commits, the fallback key is `default`. - -##### `cache:key:prefix` +- [Reuse configuration sections by using `extends`](yaml_optimization.md#use-extends-to-reuse-configuration-sections). +- Use `extends` to reuse configuration from [included configuration files](yaml_optimization.md#use-extends-and-include-together). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. +### `image` -Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles). +Use `image` to specify a Docker image that the job runs in. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). -**Possible inputs**: +**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats: -- A string -- A [predefined variables](../variables/index.md) -- A combination of both. +- `<image-name>` (Same as using `<image-name>` with the `latest` tag) +- `<image-name>:<tag>` +- `<image-name>@<digest>` -**Example of `cache:key:prefix`**: +**Example of `image`**: ```yaml +default: + image: ruby:3.0 + rspec: - script: - - echo "This rspec job uses a cache." - cache: - key: - files: - - Gemfile.lock - prefix: $CI_JOB_NAME - paths: - - vendor/ruby + script: bundle exec rspec + +rspec 2.7: + image: registry.example.com/my-group/my-project/ruby:2.7 + script: bundle exec rspec ``` -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`. +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**: +**Related topics**: -- If no file in `cache:key:files` is changed in any commits, the prefix is added to the `default` key. +- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). -#### `cache:untracked` +#### `image:name` -Use `untracked: true` to cache all files that are untracked in your Git repository: +The name of the Docker image that the job runs in. Similar to [`image`](#image) used by itself. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). -**Possible inputs**: `true` or `false` (default). +**Possible inputs**: The name of the image, including the registry path if needed, in one of these formats: -**Example of `cache:untracked`**: +- `<image-name>` (Same as using `<image-name>` with the `latest` tag) +- `<image-name>:<tag>` +- `<image-name>@<digest>` + +**Example of `image:name`**: ```yaml -rspec: - script: test - cache: - untracked: true +image: + name: "registry.example.com/my/image:latest" ``` -**Additional details**: - -- You can combine `cache:untracked` with `cache:paths` to cache all untracked files - as well as files in the configured paths. For example: +**Related topics**: - ```yaml - rspec: - script: test - cache: - untracked: true - paths: - - binaries/ - ``` +- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). -#### `cache:when` +#### `image:entrypoint` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18969) in GitLab 13.5 and GitLab Runner v13.5.0. +Command or script to execute as the container's entry point. -Use `cache:when` to define when to save the cache, based on the status of the job. +When the Docker container is created, the `entrypoint` is translated to the Docker `--entrypoint` option. +The syntax is similar to the [Dockerfile `ENTRYPOINT` directive](https://docs.docker.com/engine/reference/builder/#entrypoint), +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](#default). +[`default` section](#default). **Possible inputs**: -- `on_success` (default): Save the cache only when the job succeeds. -- `on_failure`: Save the cache only when the job fails. -- `always`: Always save the cache. +- A string. -**Example of `cache:when`**: +**Example of `image:entrypoint`**: ```yaml -rspec: - script: rspec - cache: - paths: - - rspec/ - when: 'always' +image: + name: super/sql:experimental + entrypoint: [""] ``` -This example stores the cache whether or not the job fails or succeeds. +**Related topics**: -#### `cache:policy` +- [Override the entrypoint of an image](../docker/using_docker_images.md#override-the-entrypoint-of-an-image). -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). +### `inherit` -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`. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9. -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 `inherit` to [control inheritance of globally-defined defaults and variables](../jobs/index.md#control-the-inheritance-of-default-keywords-and-global-variables). -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. +#### `inherit:default` -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +Use `inherit:default` to control the inheritance of [default keywords](#default). + +**Keyword type**: Job keyword. You can use it only as part of a job. **Possible inputs**: -- `pull` -- `push` -- `pull-push` (default) +- `true` (default) or `false` to enable or disable the inheritance of all default keywords. +- A list of specific default keywords to inherit. -**Example of `cache:policy`**: +**Example of `inherit:default`**: ```yaml -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..." +default: + retry: 2 + image: ruby:3.0 + interruptible: true -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..." +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 ``` -### `dependencies` +**Additional details**: -Use the `dependencies` keyword to define a list of jobs to fetch [artifacts](#artifacts) from. -You can also set a job to download no artifacts at all. +- You can also list default keywords to inherit on one line: `default: [keyword1, keyword2]` -If you do not use `dependencies`, all artifacts from previous stages are passed to each job. +#### `inherit:variables` + +Use `inherit:variables` to control the inheritance of [global variables](#variables) keywords. **Keyword type**: Job keyword. You can use it only as part of a job. **Possible inputs**: -- The names of jobs to fetch artifacts from. -- An empty array (`[]`), to configure the job to not download any artifacts. +- `true` (default) or `false` to enable or disable the inheritance of all global variables. +- A list of specific variables to inherit. -**Example of `dependencies`**: +**Example of `inherit:variables`**: ```yaml -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 +variables: + VARIABLE1: "This is variable 1" + VARIABLE2: "This is variable 2" + VARIABLE3: "This is variable 3" -test linux: - stage: test - script: make test:linux - dependencies: - - build:linux +job1: + script: echo "This job does not inherit any global variables." + inherit: + variables: false -deploy: - stage: deploy - script: make deploy +job2: + script: echo "This job inherits only the two listed global variables. It does not inherit 'VARIABLE3'." + inherit: + variables: + - VARIABLE1 + - VARIABLE2 ``` -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](#stages) 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](#artifactsexpire_in) or - [deleted](../pipelines/job_artifacts.md#delete-job-artifacts), then the job fails. - -### `artifacts` - -Use `artifacts` to specify a list of files and directories that are -attached to the job when it [succeeds, fails, or always](#artifactswhen). - -The artifacts are sent to GitLab after the job finishes. They are -available for download in the GitLab UI if the size is not -larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd). +- You can also list global variables to inherit on one line: `variables: [VARIABLE1, VARIABLE2]` -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`](#dependencies). +### `interruptible` -When using the [`needs`](#needs) keyword, jobs can only download -artifacts from the jobs defined in the `needs` configuration. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -Job artifacts are only collected for successful jobs by default, and -artifacts are restored after [caches](#cache). +Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes. -[Read more about artifacts](../pipelines/job_artifacts.md). +This keyword is used with the [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) +feature. When enabled, a running job with `interruptible: true` can be cancelled when +a new pipeline starts on the same branch. -#### `artifacts:exclude` +You can't cancel subsequent jobs after a job with `interruptible: false` starts. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) in GitLab 13.1 -> - Requires GitLab Runner 13.1 +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -`exclude` makes it possible to prevent files from being added to an artifacts -archive. +**Possible inputs**: -Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative -to the project directory. You can use Wildcards that use -[glob](https://en.wikipedia.org/wiki/Glob_(programming)) or -[`doublestar.PathMatch`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#PathMatch) patterns. +- `true` or `false` (default). -For example, to store all files in `binaries/`, but not `*.o` files located in -subdirectories of `binaries/`: +**Example of `interruptible`**: ```yaml -artifacts: - paths: - - binaries/ - exclude: - - binaries/**/*.o -``` +stages: + - stage1 + - stage2 + - stage3 -Unlike [`artifacts:paths`](#artifactspaths), `exclude` paths are not recursive. To exclude all of the contents of a directory, you can match them explicitly rather than matching the directory itself. +step-1: + stage: stage1 + script: + - echo "Can be canceled." + interruptible: true -For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory: +step-2: + stage: stage2 + script: + - echo "Can not be canceled." -```yaml -artifacts: - paths: - - binaries/ - exclude: - - binaries/temp/**/* +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 ``` -Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded using -`artifacts:exclude` too. +In this example, a new pipeline causes a running pipeline to be: -#### `artifacts:expire_in` +- Canceled, if only `step-1` is running or pending. +- Not canceled, after `step-2` starts. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0 behind a disabled feature flag, the latest job artifacts are kept regardless of expiry time. -> - [Made default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8, keeping latest job artifacts can be disabled at the project level. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276583) in GitLab 13.9, keeping latest job artifacts can be disabled instance-wide. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321323) in GitLab 13.12, the latest pipeline artifacts are kept regardless of expiry time. +**Additional details**: -Use `expire_in` to specify how long [job artifacts](../pipelines/job_artifacts.md) are stored before -they expire and are deleted. The `expire_in` setting does not affect: +- Only set `interruptible: true` if the job can be safely canceled after it has started, + like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments. +- To completely cancel a running pipeline, all jobs must have `interruptible: true`, + or `interruptible: false` jobs must not have started. -- Artifacts from the latest job, unless keeping the latest job artifacts is: - - [Disabled at the project level](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). - - [Disabled instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). -- [Pipeline artifacts](../pipelines/pipeline_artifacts.md). You can't specify an expiration date for - pipeline artifacts. See [When pipeline artifacts are deleted](../pipelines/pipeline_artifacts.md#when-pipeline-artifacts-are-deleted) - for more information. +### `needs` -The value of `expire_in` is an elapsed time in seconds, unless a unit is provided. Valid values -include: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) in GitLab 12.2. +> - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) in GitLab 12.8, `needs: []` lets jobs start immediately. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) in GitLab 14.2, you can refer to jobs in the same stage as the job you are configuring. -- `'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` +Use `needs` to execute jobs out-of-order. Relationships between jobs +that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md). -To expire artifacts one week after being uploaded: +You can ignore stage ordering and run some jobs without waiting for others to complete. +Jobs in multiple stages can run concurrently. -```yaml -job: - artifacts: - expire_in: 1 week -``` +**Keyword type**: Job keyword. You can use it only as part of a job. -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](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration) -(30 days by default). +**Possible inputs**: -To override the expiration date and protect artifacts from being automatically deleted: +- An array of jobs. +- An empty array (`[]`), to set the job to start as soon as the pipeline is created. -- Select **Keep** on the job page. -- [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of - `expire_in` to `never`. +**Example of `needs`**: -After their expiry, artifacts are deleted hourly by default (using a cron job), and are not -accessible anymore. +```yaml +linux:build: + stage: build + script: echo "Building linux..." -#### `artifacts:expose_as` +mac:build: + stage: build + script: echo "Building mac..." -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5. +lint: + stage: test + needs: [] + script: echo "Linting..." -Use the `expose_as` keyword to expose [job artifacts](../pipelines/job_artifacts.md) -in the [merge request](../../user/project/merge_requests/index.md) UI. +linux:rspec: + stage: test + needs: ["linux:build"] + script: echo "Running rspec on linux..." -For example, to match a single file: +mac:rspec: + stage: test + needs: ["mac:build"] + script: echo "Running rspec on mac..." -```yaml -test: - script: ["echo 'test' > file.txt"] - artifacts: - expose_as: 'artifact 1' - paths: ['file.txt'] +production: + stage: deploy + script: echo "Running production..." ``` -With this configuration, GitLab adds a link **artifact 1** to the relevant merge request -that points to `file1.txt`. To access the link, select **View exposed artifact** -below the pipeline graph in the merge request overview. - -An example that matches an entire directory: +This example creates four paths of execution: -```yaml -test: - script: ["mkdir test && echo 'test' > test/file.txt"] - artifacts: - expose_as: 'artifact 1' - paths: ['test/'] -``` +- Linter: The `lint` job runs immediately without waiting for the `build` stage + to complete because it has no needs (`needs: []`). +- Linux path: The `linux:rspec` job runs as soon as the `linux:build` + job finishes, without waiting for `mac:build` to finish. +- macOS path: The `mac:rspec` jobs runs as soon as the `mac:build` + job finishes, without waiting for `linux:build` to finish. +- The `production` job runs as soon as all previous jobs finish: + `linux:build`, `linux:rspec`, `mac:build`, `mac:rspec`. -Note the following: +**Additional details**: -- Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`. -- A maximum of 10 job artifacts per merge request can be exposed. -- Glob patterns are unsupported. -- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#download-job-artifacts) if there is more than - one file in the directory. -- For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`, - and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is: - - Enabled, GitLab automatically renders the artifact. - - Not enabled, the file is displayed in the artifacts browser. +- 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 our + [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). + - For self-managed instances, the default limit is 50. This limit [can be changed](../../administration/cicd.md#set-the-needs-job-limit). +- If `needs` refers to a job that uses the [`parallel`](#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. +- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you + can refer to jobs in the same stage as the job you are configuring. This feature is + enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) + this feature is available by default. +- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. Stages must be + explicitly defined for all jobs that use the `needs` keyword, or are referenced + in a job's `needs` section. +- In GitLab 13.9 and older, 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. -#### `artifacts:name` +#### `needs:artifacts` -Use the `name` directive to define the name of the created artifacts -archive. You can specify a unique name for every archive. The `artifacts:name` -variable can make use of any of the [predefined variables](../variables/index.md). -The default name is `artifacts`, which becomes `artifacts.zip` when you download it. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.6. -To create an archive with a name of the current job: +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. -```yaml -job: - artifacts: - name: "$CI_JOB_NAME" - paths: - - binaries/ -``` +Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are +downloaded in jobs that use `needs`. -To create an archive with a name of the current branch or tag including only -the binaries directory: +**Keyword type**: Job keyword. You can use it only as part of a job. Must be used with `needs:job`. -```yaml -job: - artifacts: - name: "$CI_COMMIT_REF_NAME" - paths: - - binaries/ -``` +**Possible inputs**: -If your branch-name contains forward slashes -(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG` -instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact. +- `true` (default) or `false`. -To create an archive with a name of the current job and the current branch or -tag including only the binaries directory: +**Example of `needs:artifacts`**: ```yaml -job: - artifacts: - name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME" - paths: - - binaries/ -``` +test-job1: + stage: test + needs: + - job: build_job1 + artifacts: true -To create an archive with a name of the current [stage](#stages) and branch name: +test-job2: + stage: test + needs: + - job: build_job2 + artifacts: false -```yaml -job: - artifacts: - name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME" - paths: - - binaries/ +test-job3: + needs: + - job: build_job1 + artifacts: true + - job: build_job2 + - build_job3 ``` ---- - -If you use **Windows Batch** to run your shell scripts you must replace -`$` with `%`: - -```yaml -job: - artifacts: - name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%" - paths: - - binaries/ -``` +In this example: -If you use **Windows PowerShell** to run your shell scripts you must replace -`$` with `$env:`: +- 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. -```yaml -job: - artifacts: - name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME" - paths: - - binaries/ -``` +**Additional details**: -#### `artifacts:paths` +- In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword + with `needs`. -Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly -link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) -patterns and: +#### `needs:project` **(PREMIUM)** -- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620), - [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). -- In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.7. -To restrict which jobs a specific job fetches artifacts from, see [dependencies](#dependencies). +Use `needs:project` to download artifacts from up to five jobs in other pipelines. +The artifacts are downloaded from the latest successful pipeline for the specified ref. -Send all files in `binaries` and `.config`: +If there is a pipeline running for the specified ref, a job with `needs:project` +does not wait for the pipeline to complete. Instead, the job downloads the artifact +from the latest pipeline that completed successfully. -```yaml -artifacts: - paths: - - binaries/ - - .config -``` +`needs:project` must be used with `job`, `ref`, and `artifacts`. -To disable artifact passing, define the job with empty [dependencies](#dependencies): +**Keyword type**: Job keyword. You can use it only as part of a job. -```yaml -job: - stage: build - script: make build - dependencies: [] -``` +**Possible inputs**: -You may want to create artifacts only for tagged releases to avoid filling the -build server storage with temporary build artifacts. +- `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. -Create artifacts only for tags (`default-job` doesn't create artifacts): +**Examples of `needs:project`**: ```yaml -default-job: - script: - - mvn test -U - rules: - - if: $CI_COMMIT_BRANCH - -release-job: +build_job: + stage: build script: - - mvn package -U - artifacts: - paths: - - target/*.war - rules: - - if: $CI_COMMIT_TAG -``` - -You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with `xyz`: - -```yaml -job: - artifacts: - paths: - - path/*xyz/* + - ls -lhR + needs: + - project: namespace/group/project-name + job: build-1 + ref: main + artifacts: true ``` -#### `artifacts:public` - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49775) in GitLab 13.8 -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's recommended for production use. - -Use `artifacts:public` to determine whether the job artifacts should be -publicly available. - -The default for `artifacts:public` is `true` which means that the artifacts in -public pipelines are available for download by anonymous and guest users: - -```yaml -artifacts: - public: true -``` +In this example, `build_job` downloads the artifacts from the latest successful `build-1` job +on the `main` branch in the `group/project-name` project. -To deny read access for anonymous and guest users to artifacts in public -pipelines, set `artifacts:public` to `false`: +In GitLab 13.3 and later, you can use [CI/CD variables](../variables/index.md) in `needs:project`, +for example: ```yaml -artifacts: - public: false +build_job: + stage: build + script: + - ls -lhR + needs: + - project: $CI_PROJECT_PATH + job: $DEPENDENCY_JOB_NAME + ref: $ARTIFACTS_DOWNLOAD_REF + artifacts: true ``` -#### `artifacts:reports` - -Use [`artifacts:reports`](#artifactsreports) to: - -- Collect test reports, code quality reports, security reports, and other artifacts generated by included templates in - jobs. -- Some of these reports are used to display information in: - - Merge requests. - - Pipeline views. - - [Security dashboards](../../user/application_security/security_dashboard/index.md). - -The test reports are collected regardless of the job results (success or failure). -You can use [`artifacts:expire_in`](#artifactsexpire_in) to set up an expiration -date for their artifacts. - -Some `artifacts:reports` types can be generated by multiple jobs in the same pipeline, and used by merge request or -pipeline features from each job. - -To be able to browse the report output files, include the [`artifacts:paths`](#artifactspaths) keyword. - -NOTE: -Combined reports in parent pipelines using [artifacts from child pipelines](#needspipelinejob) is -not supported. Track progress on adding support in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215725). - -##### `artifacts:reports:accessibility` **(FREE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 12.8. - -The `accessibility` report uses [pa11y](https://pa11y.org/) to report on the accessibility impact -of changes introduced in merge requests. - -GitLab can display the results of one or more reports in the merge request -[accessibility widget](../../user/project/merge_requests/accessibility_testing.md#accessibility-merge-request-widget). - -For more information, see [Accessibility testing](../../user/project/merge_requests/accessibility_testing.md). - -##### `artifacts:reports:api_fuzzing` **(ULTIMATE)** - -> - Introduced in GitLab 13.4. -> - Requires GitLab Runner 13.4 or later. - -The `api_fuzzing` report collects [API Fuzzing bugs](../../user/application_security/api_fuzzing/index.md) -as artifacts. - -GitLab can display the results of one or more reports in: - -- The merge request [security widget](../../user/application_security/api_fuzzing/index.md#view-details-of-an-api-fuzzing-vulnerability). -- The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). -- The [security dashboard](../../user/application_security/api_fuzzing/index.md#security-dashboard). - -##### `artifacts:reports:browser_performance` **(PREMIUM)** - -> [Name changed](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) from `artifacts:reports:performance` in GitLab 14.0. - -The `browser_performance` report collects [Browser Performance Testing metrics](../../user/project/merge_requests/browser_performance_testing.md) -as artifacts. - -GitLab can display the results of one report in the merge request -[browser performance testing widget](../../user/project/merge_requests/browser_performance_testing.md#how-browser-performance-testing-works). - -GitLab cannot display the combined results of multiple `browser_performance` reports. - -##### `artifacts:reports:cluster_image_scanning` **(ULTIMATE)** - -> - Introduced in GitLab 14.1. -> - Requires GitLab Runner 14.1 and above. - -The `cluster_image_scanning` report collects `CLUSTER_IMAGE_SCANNING` vulnerabilities. The collected -`CLUSTER_IMAGE_SCANNING` report uploads to GitLab as an artifact. - -GitLab can display the results of one or more reports in: - -- The [security dashboard](../../user/application_security/security_dashboard/index.md). -- The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). - -##### `artifacts:reports:cobertura` - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. - -The `cobertura` report collects [Cobertura coverage XML files](../../user/project/merge_requests/test_coverage_visualization.md). -The collected Cobertura coverage reports upload to GitLab as an artifact. - -GitLab can display the results of one or more reports in the merge request -[diff annotations](../../user/project/merge_requests/test_coverage_visualization.md). - -Cobertura was originally developed for Java, but there are many third-party ports for other languages such as -JavaScript, Python, and Ruby. - -##### `artifacts:reports:codequality` - -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. - -The `codequality` report collects [code quality issues](../../user/project/merge_requests/code_quality.md). The -collected code quality report uploads to GitLab as an artifact. +**Additional details**: -GitLab can display the results of: +- 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 at least the Reporter 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`](#trigger). +- When using `needs:project` to download artifacts from another pipeline, the job does not wait for + the needed job to complete. [Directed acyclic graph](../directed_acyclic_graph/index.md) + behavior 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`](#parallel). +- Support for [CI/CD variables](../variables/index.md) in `project`, `job`, and `ref` was + [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202093) in GitLab 13.3. + [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235761) in GitLab 13.4. -- One or more reports in the merge request [code quality widget](../../user/project/merge_requests/code_quality.md#code-quality-widget). -- Only one report in: - - The merge request [diff annotations](../../user/project/merge_requests/code_quality.md#code-quality-in-diff-view). - Track progress on adding support for multiple reports in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328257). - - The [full report](../metrics_reports.md). Track progress on adding support for multiple reports in - [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/9014). +**Related topics**: -##### `artifacts:reports:container_scanning` **(ULTIMATE)** +- To download artifacts between [parent-child pipelines](../pipelines/parent_child_pipelines.md), + use [`needs:pipeline:job`](#needspipelinejob). -The `container_scanning` report collects [Container Scanning vulnerabilities](../../user/application_security/container_scanning/index.md). -The collected Container Scanning report uploads to GitLab as an artifact. +#### `needs:pipeline:job` -GitLab can display the results of one or more reports in: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab 13.7. -- The merge request [container scanning widget](../../user/application_security/container_scanning/index.md). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). -- The [security dashboard](../../user/application_security/security_dashboard/index.md). -- The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). +A [child pipeline](../pipelines/parent_child_pipelines.md) can download artifacts from a job in +its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy. -##### `artifacts:reports:coverage_fuzzing` **(ULTIMATE)** +**Keyword type**: Job keyword. You can use it only as part of a job. -> - Introduced in GitLab 13.4. -> - Requires GitLab Runner 13.4 or later. +**Possible inputs**: -The `coverage_fuzzing` report collects [coverage fuzzing bugs](../../user/application_security/coverage_fuzzing/index.md). -The collected coverage fuzzing report uploads to GitLab as an artifact. -GitLab can display the results of one or more reports in: +- `needs:pipeline`: A pipeline ID. Must be a pipeline present in the same parent-child pipeline hierarchy. +- `job`: The job to download artifacts from. -- The merge request [coverage fuzzing widget](../../user/application_security/coverage_fuzzing/index.md#interacting-with-the-vulnerabilities). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). -- The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). -- The [security dashboard](../../user/application_security/security_dashboard/index.md). +**Example of `needs:pipeline:job`**: -##### `artifacts:reports:dast` **(ULTIMATE)** +- Parent pipeline (`.gitlab-ci.yml`): -The `dast` report collects [DAST vulnerabilities](../../user/application_security/dast/index.md). The collected DAST -report uploads to GitLab as an artifact. + ```yaml + create-artifact: + stage: build + script: echo "sample artifact" > artifact.txt + artifacts: + paths: [artifact.txt] -GitLab can display the results of one or more reports in: + child-pipeline: + stage: test + trigger: + include: child.yml + strategy: depend + variables: + PARENT_PIPELINE_ID: $CI_PIPELINE_ID + ``` -- The merge request [security widget](../../user/application_security/dast/index.md#view-details-of-a-vulnerability-detected-by-dast). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). -- The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). -- The [security dashboard](../../user/application_security/security_dashboard/index.md). +- Child pipeline (`child.yml`): -##### `artifacts:reports:dependency_scanning` **(ULTIMATE)** + ```yaml + use-artifact: + script: cat artifact.txt + needs: + - pipeline: $PARENT_PIPELINE_ID + job: create-artifact + ``` -The `dependency_scanning` report collects [Dependency Scanning vulnerabilities](../../user/application_security/dependency_scanning/index.md). -The collected Dependency Scanning report uploads to GitLab as an 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. -GitLab can display the results of one or more reports in: +**Additional details**: -- The merge request [dependency scanning widget](../../user/application_security/dependency_scanning/index.md#overview). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). -- The [security dashboard](../../user/application_security/security_dashboard/index.md). -- The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). -- The [dependency list](../../user/application_security/dependency_list/). +- 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`](#needsartifacts). -##### `artifacts:reports:dotenv` +#### `needs:optional` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30680) in GitLab 13.10. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323891) in GitLab 14.0. -The `dotenv` report collects a set of environment variables as artifacts. +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. -The collected variables are registered as runtime-created variables of the job, -which is useful to [set dynamic environment URLs after a job finishes](../environments/index.md#set-dynamic-environment-urls-after-a-job-finishes). +Jobs that use [`rules`](#rules), [`only`, or `except`](#only--except), might +not always exist in a pipeline. When the pipeline is created, GitLab checks the `needs` +relationships before starting it. Without `optional: true`, needs relationships that +point to a job that does not exist stops the pipeline from starting and causes a pipeline +error similar to: -The exceptions to the [original dotenv rules](https://github.com/motdotla/dotenv#rules) are: +- `'job1' job needs 'job2' job, but it was not added to the pipeline` -- The variable key can contain only letters, digits, and underscores (`_`). -- The maximum size of the `.env` file is 5 KB. -- In GitLab 13.5 and older, the maximum number of inherited variables is 10. -- In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/247913), - the maximum number of inherited variables is 20. -- Variable substitution in the `.env` file is not supported. -- The `.env` file can't have empty lines or comments (starting with `#`). -- Key values in the `env` file cannot have spaces or newline characters (`\n`), including when using single or double quotes. -- Quote escaping during parsing (`key = 'value'` -> `{key: "value"}`) is not supported. +**Keyword type**: Job keyword. You can use it only as part of a job. -##### `artifacts:reports:junit` +**Possible inputs**: -The `junit` report collects [JUnit report format XML files](https://www.ibm.com/docs/en/adfz/developer-for-zos/14.1.0?topic=formats-junit-xml-format). -The collected Unit test reports upload to GitLab as an artifact. Although JUnit was originally developed in Java, there -are many third-party ports for other languages such as JavaScript, Python, and Ruby. +- `job`: The job to make optional. +- `true` or `false` (default). -See [Unit test reports](../unit_test_reports.md) for more details and examples. -Below is an example of collecting a JUnit report format XML file from Ruby's RSpec test tool: +**Example of `needs:optional`**: ```yaml +build: + stage: build + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + rspec: stage: test - script: - - bundle install - - rspec --format RspecJunitFormatter --out rspec.xml - artifacts: - reports: - junit: rspec.xml + needs: + - job: build + optional: true ``` -GitLab can display the results of one or more reports in: - -- The merge request [code quality widget](../../ci/unit_test_reports.md#how-it-works). -- The [full report](../../ci/unit_test_reports.md#viewing-unit-test-reports-on-gitlab). - -Some JUnit tools export to multiple XML files. You can specify multiple test report paths in a single job to -concatenate them into a single file. Use either: - -- A filename pattern (`junit: rspec-*.xml`). -- an array of filenames (`junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]`). -- A Combination of both (`junit: [rspec.xml, test-results/TEST-*.xml]`). - -##### `artifacts:reports:license_scanning` **(ULTIMATE)** - -> Introduced in GitLab 12.8. - -The License Compliance report collects [Licenses](../../user/compliance/license_compliance/index.md). The License -Compliance report uploads to GitLab as an artifact. - -GitLab can display the results of one or more reports in: - -- The merge request [license compliance widget](../../user/compliance/license_compliance/index.md). -- The [license list](../../user/compliance/license_compliance/index.md#license-list). - -##### `artifacts:reports:load_performance` **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in GitLab 13.2. -> - Requires GitLab Runner 11.5 and above. - -The `load_performance` report collects [Load Performance Testing metrics](../../user/project/merge_requests/load_performance_testing.md). -The report is uploaded to GitLab as an artifact. - -GitLab can display the results of only one report in the merge request -[load testing widget](../../user/project/merge_requests/load_performance_testing.md#how-load-performance-testing-works). - -GitLab cannot display the combined results of multiple `load_performance` reports. - -##### `artifacts:reports:metrics` **(PREMIUM)** +In this example: -The `metrics` report collects [Metrics](../metrics_reports.md). The collected Metrics report uploads to GitLab as an -artifact. +- When the branch is the default branch, the `build` job exists in the pipeline, and the `rspec` + job waits for it to complete before starting. +- When the branch is not the default branch, the `build` job does not exist in the pipeline. + The `rspec` job runs immediately (similar to `needs: []`) because its `needs` + relationship to the `build` job is optional. -GitLab can display the results of one or more reports in the merge request -[metrics reports widget](../../ci/metrics_reports.md#metrics-reports). +#### `needs:pipeline` -##### `artifacts:reports:requirements` **(ULTIMATE)** +You can mirror the pipeline status from an upstream pipeline to a bridge job by +using the `needs:pipeline` keyword. The latest pipeline status from the default branch is +replicated to the bridge job. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. +**Keyword type**: Job keyword. You can use it only as part of a job. -The `requirements` report collects `requirements.json` files. The collected Requirements report uploads to GitLab as an -artifact and existing [requirements](../../user/project/requirements/index.md) are marked as Satisfied. +**Possible inputs**: -GitLab can display the results of one or more reports in the -[project requirements](../../user/project/requirements/index.md#view-a-requirement). +- 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`. -##### `artifacts:reports:sast` +**Example of `needs:pipeline`**: -> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. +```yaml +upstream_bridge: + stage: test + needs: + pipeline: other/project +``` -The `sast` report collects [SAST vulnerabilities](../../user/application_security/sast/index.md). The collected SAST -report uploads to GitLab as an artifact. +**Additional details**: -GitLab can display the results of one or more reports in: +- If you add the `job` keyword to `needs:pipeline`, the job no longer mirrors the + pipeline status. The behavior changes to [`needs:pipeline:job`](#needspipelinejob). -- The merge request [SAST widget](../../user/application_security/sast/index.md#static-application-security-testing-sast). -- The [security dashboard](../../user/application_security/security_dashboard/index.md). +### `only` / `except` -##### `artifacts:reports:secret_detection` +NOTE: +`only` and `except` are not being actively developed. [`rules`](#rules) is the preferred +keyword to control when to add jobs to pipelines. -> - Introduced in GitLab 13.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) to GitLab Free in 13.3. -> - Requires GitLab Runner 11.5 and above. +You can use `only` and `except` to control when to add jobs to pipelines. -The `secret-detection` report collects [detected secrets](../../user/application_security/secret_detection/index.md). -The collected Secret Detection report is uploaded to GitLab. +- Use `only` to define when a job runs. +- Use `except` to define when a job **does not** run. -GitLab can display the results of one or more reports in: +Four keywords can be used with `only` and `except`: -- The merge request [secret scanning widget](../../user/application_security/secret_detection/index.md). -- The [pipeline **Security** tab](../../user/application_security/index.md#view-security-scan-information-in-the-pipeline-security-tab). -- The [security dashboard](../../user/application_security/security_dashboard/index.md). +- [`refs`](#onlyrefs--exceptrefs) +- [`variables`](#onlyvariables--exceptvariables) +- [`changes`](#onlychanges--exceptchanges) +- [`kubernetes`](#onlykubernetes--exceptkubernetes) -##### `artifacts:reports:terraform` +See [specify when jobs run with `only` and `except`](../jobs/job_control.md#specify-when-jobs-run-with-only-and-except) +for more details and examples. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0. -> - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. +#### `only:refs` / `except:refs` -The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/iac/mr_integration.md#configure-terraform-report-artifacts). -The collected Terraform plan report uploads to GitLab as an artifact. +Use the `only:refs` and `except:refs` keywords to control when to add jobs to a +pipeline based on branch names or pipeline types. -GitLab can display the results of one or more reports in the merge request -[terraform widget](../../user/infrastructure/iac/mr_integration.md#output-terraform-plan-information-into-a-merge-request). +**Keyword type**: Job keyword. You can use it only as part of a job. -For more information, see [Output `terraform plan` information into a merge request](../../user/infrastructure/iac/mr_integration.md). +**Possible inputs**: An array including any number of: -#### `artifacts:untracked` +- Branch names, for example `main` or `my-feature-branch`. +- [Regular expressions](../jobs/job_control.md#only--except-regex-syntax) + that match against branch names, for example `/^feature-.*/`. +- The following keywords: -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` file. + | **Value** | **Description** | + | -------------------------|-----------------| + | `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | + | `branches` | When the Git reference for a pipeline is a branch. | + | `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. | + | `external` | When you use CI services other than GitLab. | + | `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). | + | `merge_requests` | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../pipelines/merge_request_pipelines.md), [merged results pipelines](../pipelines/pipelines_for_merged_results.md), and [merge trains](../pipelines/merge_trains.md). | + | `pipelines` | For [multi-project pipelines](../pipelines/multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../pipelines/multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](#trigger) keyword. | + | `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. | + | `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | + | `tags` | When the Git reference for a pipeline is a tag. | + | `triggers` | For pipelines created by using a [trigger token](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). | + | `web` | For pipelines created by selecting **Run pipeline** in the GitLab UI, from the project's **CI/CD > Pipelines** section. | -Send all Git untracked files: +**Example of `only:refs` and `except:refs`**: ```yaml -artifacts: - untracked: true -``` - -Send all Git untracked files and files in `binaries`: +job1: + script: echo + only: + - main + - /^issue-.*$/ + - merge_requests -```yaml -artifacts: - untracked: true - paths: - - binaries/ +job2: + script: echo + except: + - main + - /^stable-branch.*$/ + - schedules ``` -Send all untracked files but [exclude](#artifactsexclude) `*.txt`: +**Additional details**: -```yaml -artifacts: - untracked: true - exclude: - - "*.txt" -``` +- Scheduled pipelines run on specific branches, so jobs configured with `only: branches` + run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches` + from running on scheduled pipelines. +- `only` or `except` used without any other keywords are equivalent to `only: refs` + or `except: refs`. For example, the following two jobs configurations have the same + behavior: -#### `artifacts:when` + ```yaml + job1: + script: echo + only: + - branches -Use `artifacts:when` to upload artifacts on job failure or despite the -failure. + job2: + script: echo + only: + refs: + - branches + ``` -`artifacts:when` can be set to one of the following values: +- If a job does not use `only`, `except`, or [`rules`](#rules), then `only` is set to `branches` + and `tags` by default. -1. `on_success` (default): Upload artifacts only when the job succeeds. -1. `on_failure`: Upload artifacts only when the job fails. -1. `always`: Always upload artifacts. For example, when - [uploading artifacts](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab) required to - troubleshoot failing tests. + For example, `job1` and `job2` are equivalent: -For example, to upload artifacts only when a job fails: + ```yaml + job1: + script: echo "test" -```yaml -job: - artifacts: - when: on_failure -``` + job2: + script: echo "test" + only: + - branches + - tags + ``` -### `coverage` +#### `only:variables` / `except:variables` -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. +Use the `only:variables` or `except:variables` keywords to control when to add jobs +to a pipeline, based on the status of [CI/CD variables](../variables/index.md). -To extract the code coverage value in the matching line, GitLab uses this -regular expression: `\d+(\.\d+)?`. +**Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: A regular expression. Must start and end with `/`. +**Possible inputs**: -**Example of `coverage`**: +- An array of [CI/CD variable expressions](../jobs/job_control.md#cicd-variable-expressions). + +**Example of `only:variables`**: ```yaml -job1: - script: rspec - coverage: '/Code coverage: \d+\.\d+/' +deploy: + script: cap staging deploy + only: + variables: + - $RELEASE == "staging" + - $STAGING ``` -In this example: - -1. GitLab checks the job log for a line that matches the regular expression. A line - like `Code coverage: 67.89` would match. -1. GitLab then checks the line to find a match to `\d+(\.\d+)?`. The sample matching - line above gives a code coverage of `67.89`. +**Related topics**: -**Additional details**: +- [`only:variables` and `except:variables` examples](../jobs/job_control.md#only-variables--except-variables-examples). -- If there is more than one matched line in the job output, the last line is used. -- Leading zeros are removed. -- Coverage output from [child pipelines](../pipelines/parent_child_pipelines.md) - is not recorded or displayed. Check [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/280818) - for more details. +#### `only:changes` / `except:changes` -### `dast_configuration` **(ULTIMATE)** +Use the `changes` keyword with `only` to run a job, or with `except` to skip a job, +when a Git push event modifies a file. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5981) in GitLab 14.1. +Use `changes` in pipelines with the following refs: -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`. +- `branches` +- `external_pull_requests` +- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests)) -**Keyword type**: Job keyword. You can use only as part of a job. +**Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: One each of `site_profile` and `scanner_profile`. +**Possible inputs**: An array including any number of: -- 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. +- Paths to files. +- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory + and all its subdirectories, for example `path/to/directory/**/*`. +- Wildcard ([glob](https://en.wikipedia.org/wiki/Glob_(programming))) 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 `dast_configuration`**: +**Example of `only:changes`**: ```yaml -stages: - - build - - dast - -include: - - template: DAST.gitlab-ci.yml - -dast: - dast_configuration: - site_profile: "Example Co" - scanner_profile: "Quick Passive Test" +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + only: + refs: + - branches + changes: + - Dockerfile + - docker/scripts/* + - dockerfiles/**/* + - more_scripts/*.{rb,py,sh} + - "**/*.json" ``` -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. +- `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). +- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`, + `changes` can't determine if a given file is new or old and always returns `true`. +- If you use `only: changes` with other refs, jobs ignore the changes and always run. +- If you use `except: changes` with other refs, jobs ignore the changes and never run. **Related topics**: -- [Site profile](../../user/application_security/dast/index.md#site-profile). -- [Scanner profile](../../user/application_security/dast/index.md#scanner-profile). - -### `retry` +- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples). +- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), + you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests). +- Use `changes` with [new branches or tags *without* pipelines for merge requests](../jobs/job_control.md#use-onlychanges-without-pipelines-for-merge-requests). +- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines). -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. +#### `only:kubernetes` / `except:kubernetes` -When a job fails, the job is processed up to two more times, until it succeeds or -reaches the maximum number of retries. +Use `only:kubernetes` or `except:kubernetes` to control if jobs are added to the pipeline +when the Kubernetes service is active in the project. -By default, all failure types cause the job to be retried. Use [`retry:when`](#retrywhen) -to select which failures to retry on. +**Keyword type**: Job-specific. You can use it only as part of a job. -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +**Possible inputs**: -**Possible inputs**: `0` (default), `1`, or `2`. +- The `kubernetes` strategy accepts only the `active` keyword. -**Example of `retry`**: +**Example of `only:kubernetes`**: ```yaml -test: - script: rspec - retry: 2 +deploy: + only: + kubernetes: active ``` -#### `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`](#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](#default). - -**Possible inputs**: A single failure type, or an array of one or more failure types: - -<!-- - If you change any of the values below, make sure to update the `RETRY_WHEN_IN_DOCUMENTATION` - array in `spec/lib/gitlab/ci/config/entry/retry_spec.rb`. - The test there makes sure that all documented - values are valid as a configuration option and therefore should always - stay in sync with this documentation. ---> - -- `always`: Retry on any failure (default). -- `unknown_failure`: Retry when the failure reason is unknown. -- `script_failure`: Retry when the script failed. -- `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 a structural integrity problem detected. +In this example, the `deploy` job runs only when the Kubernetes service is active +in the project. -**Example of `retry:when`** (single failure type): +### `pages` -```yaml -test: - script: rspec - retry: - max: 2 - when: runner_system_failure -``` +Use `pages` to define a [GitLab Pages](../../user/project/pages/index.md) job that +uploads static content to GitLab. The content is then published as a website. -If there is a failure other than a runner system failure, the job is not retried. +**Keyword type**: Job name. -**Example of `retry:when`** (array of failure types): +**Example of `pages`**: ```yaml -test: - script: rspec - retry: - max: 2 - when: - - runner_system_failure - - stuck_or_timeout_failure +pages: + stage: deploy + script: + - mkdir .public + - cp -r * .public + - mv .public public + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` -**Related topics**: - -You can specify the number of [retry attempts for certain stages of job execution](../runners/configure_runners.md#job-stages-attempts) -using variables. - -### `timeout` - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3. - -Use `timeout` to configure a timeout for a specific job. If the job runs for longer -than the timeout, the job fails. - -The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run). -but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). - -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). - -**Possible inputs**: A period of time written in natural language. For example, these are all equivalent: - -- `3600 seconds` -- `60 minutes` -- `one hour` +This example moves all files from the root of the project to the `public/` directory. +The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop. -**Example of `timeout`**: +**Additional details**: -```yaml -build: - script: build.sh - timeout: 3 hours 30 minutes +You must: -test: - script: rspec - timeout: 3h 30m -``` +- Place any static content in a `public/` directory. +- Define [`artifacts`](#artifacts) with a path to the `public/` directory. ### `parallel` @@ -3401,7 +2574,9 @@ 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. -**Possible inputs**: A numeric value from `2` to `50`. +**Possible inputs**: + +- A numeric value from `2` to `50`. **Example of `parallel`**: @@ -3434,7 +2609,9 @@ Multiple runners must exist, or a single runner must be configured to run multip **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: A numeric value from `2` to `50`. +**Possible inputs**: + +- A numeric value from `2` to `50`. **Example of `parallel:matrix`**: @@ -3477,175 +2654,6 @@ deploystacks: [vultr, processing] - [Run a one-dimensional matrix of parallel jobs](../jobs/job_control.md#run-a-one-dimensional-matrix-of-parallel-jobs). - [Run a matrix of triggered parallel jobs](../jobs/job_control.md#run-a-matrix-of-parallel-trigger-jobs). -### `trigger` - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in GitLab Premium 11.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. - -Use `trigger` to start a downstream pipeline that is either: - -- [A multi-project pipeline](../pipelines/multi_project_pipelines.md). -- [A child pipeline](../pipelines/parent_child_pipelines.md). - -**Keyword type**: Job keyword. You can use it only as part of a job. - -**Possible inputs**: - -- For multi-project pipelines, path to the downstream project. -- For child pipelines, path to the child pipeline CI/CD configuration file. - -**Example of `trigger` for multi-project pipeline**: - -```yaml -rspec: - stage: test - script: bundle exec rspec - -staging: - stage: deploy - trigger: my/deployment -``` - -**Example of `trigger` for child pipelines**: - -```yaml -trigger_job: - trigger: - include: path/to/child-pipeline.yml -``` - -**Additional details**: - -- Jobs with `trigger` can only use a [limited set of keywords](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file). - For example, you can't run commands with [`script`](#script), [`before_script`](#before_script), - or [`after_script`](#after_script). -- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you - can use [`when:manual`](#when) in the same job as `trigger`. In GitLab 13.4 and - earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. -- In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can - view which job triggered a downstream pipeline in the [pipeline graph](../pipelines/index.md#visualize-pipelines). - -**Related topics**: - -- [Multi-project pipeline configuration examples](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file). -- [Child pipeline configuration examples](../pipelines/parent_child_pipelines.md#examples). -- To force a rebuild of a specific branch, tag, or commit, you can - [use an API call with a trigger token](../triggers/index.md). - The trigger token is different than the `trigger` keyword. - -#### `trigger:strategy` - -Use `trigger:strategy` to force the `trigger` job to wait for the downstream pipeline to complete -before it is marked as **success**. - -This behavior is different than the default, which is for the `trigger` job to be marked as -**success** as soon as the downstream pipeline is created. - -This setting makes your pipeline execution linear rather than parallel. - -**Example of `trigger:strategy`**: - -```yaml -trigger_job: - trigger: - include: path/to/child-pipeline.yml - strategy: depend -``` - -In this example, jobs from subsequent stages wait for the triggered pipeline to -successfully complete before starting. - -### `interruptible` - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. - -Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes. - -This keyword is used with the [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) -feature. When enabled, a running job with `interruptible: true` can be cancelled when -a new pipeline starts on the same branch. - -You can't cancel subsequent jobs after a job with `interruptible: false` starts. - -**Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). - -**Possible inputs**: `true` or `false` (default). - -**Example of `interruptible`**: - -```yaml -stages: - - stage1 - - stage2 - - stage3 - -step-1: - stage: stage1 - script: - - echo "Can be canceled." - interruptible: true - -step-2: - stage: stage2 - script: - - echo "Can not be canceled." - -step-3: - stage: stage3 - script: - - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible." - interruptible: true -``` - -In this example, a new pipeline causes a running pipeline to be: - -- Canceled, if only `step-1` is running or pending. -- Not canceled, after `step-2` starts. - -**Additional details**: - -- Only set `interruptible: true` if the job can be safely canceled after it has started, - like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments. -- To completely cancel a running pipeline, all jobs must have `interruptible: true`, - or `interruptible: false` jobs must not have started. - -### `resource_group` - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7. - -Use `resource_group` to create a [resource group](../resource_groups/index.md) 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 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. - -**Possible inputs**: Only letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. -It can't start or end with `/`. - -**Example of `resource_group`**: - -```yaml -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](../resource_groups/index.md#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines). - ### `release` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 13.2. @@ -3660,7 +2668,7 @@ you can use this image from the GitLab Container Registry: `registry.gitlab.com/ **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: The `release:` subkeys: +**Possible inputs**: The `release` subkeys: - [`tag_name`](#releasetag_name) - [`name`](#releasename) (optional) @@ -3679,7 +2687,7 @@ you can use this image from the GitLab Container Registry: `registry.gitlab.com/ rules: - if: $CI_COMMIT_TAG # Run this job when a tag is created manually script: - - echo 'Running the release job.' + - echo "Running the release job." release: name: 'Release $CI_COMMIT_TAG' description: 'Release created using the release-cli.' @@ -3697,7 +2705,7 @@ This example creates a release: ```yaml script: - - echo 'release job' + - echo "release job" ``` An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/223856) exists to remove this requirement. @@ -3723,7 +2731,9 @@ New tags use the SHA associated with the pipeline. **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: A tag name. Can use [CI/CD variables](../variables/index.md). +**Possible inputs**: + +- A tag name. Can use [CI/CD variables](../variables/index.md). **Example of `release:tag_name`**: @@ -3735,7 +2745,7 @@ To create a release when a new tag is added to the project: ```yaml job: - script: echo 'Running the release job for the new tag.' + script: echo "Running the release job for the new tag." release: tag_name: $CI_COMMIT_TAG description: 'Release description' @@ -3748,7 +2758,7 @@ should **not** configure the job to run only for new tags. A semantic versioning ```yaml job: - script: echo 'Running the release job and creating a new tag.' + script: echo "Running the release job and creating a new tag." release: tag_name: ${MAJOR}_${MINOR}_${REVISION} description: 'Release description' @@ -3762,7 +2772,9 @@ The release name. If omitted, it is populated with the value of `release: tag_na **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: A text string. +**Possible inputs**: + +- A text string. **Example of `release:name`**: @@ -3849,6 +2861,405 @@ assets: link_type: 'other' # optional ``` +### `resource_group` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7. + +Use `resource_group` to create a [resource group](../resource_groups/index.md) 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 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. + +**Possible inputs**: + +- Only letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. + It can't start or end with `/`. + +**Example of `resource_group`**: + +```yaml +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](../resource_groups/index.md#pipeline-level-concurrency-control-with-cross-projectparent-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`](#retrywhen) +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](#default). + +**Possible inputs**: + +- `0` (default), `1`, or `2`. + +**Example of `retry`**: + +```yaml +test: + script: rspec + retry: 2 +``` + +#### `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`](#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](#default). + +**Possible inputs**: + +- A single failure type, or an array of one or more failure types: + +<!-- + If you change any of the values below, make sure to update the `RETRY_WHEN_IN_DOCUMENTATION` + array in `spec/lib/gitlab/ci/config/entry/retry_spec.rb`. + The test there makes sure that all documented + values are valid as a configuration option and therefore should always + stay in sync with this documentation. +--> + +- `always`: Retry on any failure (default). +- `unknown_failure`: Retry when the failure reason is unknown. +- `script_failure`: Retry when the script failed. +- `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 a structural integrity problem detected. + +**Example of `retry:when`** (single failure type): + +```yaml +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): + +```yaml +test: + script: rspec + retry: + max: 2 + when: + - runner_system_failure + - stuck_or_timeout_failure +``` + +**Related topics**: + +You can specify the number of [retry attempts for certain stages of job execution](../runners/configure_runners.md#job-stages-attempts) +using variables. + +### `rules` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3. + +Use `rules` to include or exclude jobs in pipelines. + +Rules are evaluated when the pipeline is created, and evaluated *in order* +until the first match. When a match is found, the job is either included or excluded from the pipeline, +depending on the configuration. + +You cannot use dotenv variables created in job scripts in rules, because rules are evaluated before any jobs run. + +`rules` replaces [`only/except`](#only--except) and they can't be used together +in the same job. If you configure one job to use both keywords, the GitLab returns +a `key may not be used with rules` error. + +`rules` accepts an array of rules defined with: + +- `if` +- `changes` +- `exists` +- `allow_failure` +- `variables` +- `when` + +You can combine multiple keywords together for [complex rules](../jobs/job_control.md#complex-rules). + +The job is added to the pipeline: + +- If an `if`, `changes`, or `exists` rule matches and also has `when: on_success` (default), + `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`. + +You can use [`!reference` tags](yaml_optimization.md#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs) +in different jobs. + +#### `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 no `if` statements are true, do not add the job to the pipeline. + +`if` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md) +or [custom CI/CD variables](../variables/index.md#custom-cicd-variables). + +**Keyword type**: Job-specific and pipeline-specific. You can use it as part of a job +to configure the job behavior, or with [`workflow`](#workflow) to configure the pipeline behavior. + +**Possible inputs**: + +- A [CI/CD variable expression](../jobs/job_control.md#cicd-variable-expressions). + +**Example of `rules:if`**: + +```yaml +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**: + +- 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 define `when` once per rule, or once at the job-level, which applies to + all rules. You can't mix `when` at the job-level with `when` in rules. +- Unlike variables in [`script`](../variables/index.md#use-cicd-variables-in-job-scripts) + sections, variables in rules expressions are always formatted as `$VARIABLE`. + - You can use `rules:if` with `include` to [conditionally include other configuration files](includes.md#use-rules-with-include). + +**Related topics**: + +- [Common `if` expressions for `rules`](../jobs/job_control.md#common-if-clauses-for-rules). +- [Avoid duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines). + +#### `rules:changes` + +Use `rules:changes` to specify when to add a job to a pipeline by checking for changes +to specific files. + +WARNING: +You should use `rules: changes` only with **branch pipelines** or **merge request pipelines**. +You can use `rules: changes` with other pipeline types, but `rules: changes` always +evaluates to true when there is no Git `push` event. Tag pipelines, scheduled pipelines, +and so on do **not** have a Git `push` event associated with them. A `rules: changes` job +is **always** added to those pipelines if there is no `if` that limits the job to +branch or merge request pipelines. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- An array of file paths. In GitLab 13.6 and later, [file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges). + +**Example of `rules:changes`**: + +```yaml +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 +``` + +- If the pipeline is a merge request pipeline, check `Dockerfile` 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 `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`). + +**Additional details**: + +- `rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychanges--exceptchanges). +- You can use `when: never` to implement a rule similar to [`except:changes`](#onlychanges--exceptchanges). +- `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). + +#### `rules:exists` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. + +Use `exists` to run a job when certain files exist in the repository. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- An array of file paths. Paths are relative to the project directory (`$CI_PROJECT_DIR`) + and can't directly link outside it. File paths can use glob patterns. + +**Example of `rules:exists`**: + +```yaml +job: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + rules: + - exists: + - Dockerfile +``` + +`job` runs if a `Dockerfile` exists anywhere in the repository. + +**Additional details**: + +- Glob patterns are interpreted with Ruby [`File.fnmatch`](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch) + with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. +- For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns or + file paths. After the 10,000th check, rules with patterned globs always match. + In other words, the `exists` rule always assumes a match in projects with more + than 10,000 files. +- `exists` resolves to `true` if any of the listed files are found (an `OR` operation). + +#### `rules:allow_failure` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8. + +Use [`allow_failure: true`](#allow_failure) in `rules` to allow a job to fail +without stopping the pipeline. + +You can also use `allow_failure: true` with a manual job. The pipeline continues +running without waiting for the result of the manual job. `allow_failure: false` +combined with `when: manual` in rules causes the pipeline to wait for the manual +job to run before continuing. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- `true` or `false`. Defaults to `false` if not defined. + +**Example of `rules:allow_failure`**: + +```yaml +job: + script: echo "Hello, Rules!" + rules: + - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH' + when: manual + allow_failure: true +``` + +If the rule matches, then the job is a manual job with `allow_failure: true`. + +**Additional details**: + +- The rule-level `rules:allow_failure` overrides the job-level [`allow_failure`](#allow_failure), + and only applies when the specific rule triggers the job. + +#### `rules:variables` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209864) in GitLab 13.7. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289803) in GitLab 13.10. + +Use [`variables`](#variables) in `rules` to define variables for specific conditions. + +**Keyword type**: Job-specific. You can use it only as part of a job. + +**Possible inputs**: + +- A hash of variables in the format `VARIABLE-NAME: value`. + +**Example of `rules:variables`**: + +```yaml +job: + variables: + DEPLOY_VARIABLE: "default-deploy" + rules: + - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH + variables: # Override DEPLOY_VARIABLE defined + DEPLOY_VARIABLE: "deploy-production" # at the job level. + - if: $CI_COMMIT_REF_NAME =~ /feature/ + variables: + IS_A_FEATURE: "true" # Define a new variable. + script: + - echo "Run script with $DEPLOY_VARIABLE as an argument" + - echo "Run another script if $IS_A_FEATURE exists" +``` + +### `script` + +Use `script` to specify commands for the runner to execute. + +All jobs except [trigger jobs](#trigger) require a `script` keyword. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: An array including: + +- Single line commands. +- Long commands [split over multiple lines](script.md#split-long-commands). +- [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). + +**Example of `script`**: + +```yaml +job1: + script: "bundle exec rspec" + +job2: + script: + - uname -a + - bundle exec rspec +``` + +**Additional details**: + +- When you use [these special characters in `script`](script.md#use-special-characters-with-script), you must use single quotes (`'`) or double quotes (`"`) . + +**Related topics**: + +- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes). +- [Use color codes with `script`](script.md#add-color-codes-to-script-output) + to make job logs easier to review. +- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) + to simplify job log output. + ### `secrets` **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) in GitLab 13.4. @@ -3926,7 +3337,9 @@ the secret value directly in the variable. **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: `true` (default) or `false`. +**Possible inputs**: + +- `true` (default) or `false`. **Example of `secrets:file`**: @@ -3943,118 +3356,323 @@ job: - The `file` keyword is a setting for the CI/CD variable and must be nested under the CI/CD variable name, not in the `vault` section. -### `pages` +### `services` -Use `pages` to define a [GitLab Pages](../../user/project/pages/index.md) job that -uploads static content to GitLab. The content is then published as a website. +Use `services` to specify an additional Docker image to run scripts in. The [`services` image](../services/index.md) is linked +to the image specified in the [`image`](#image) keyword. -**Keyword type**: Job name. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). -**Example of `pages`**: +**Possible inputs**: The name of the services image, including the registry path if needed, in one of these formats: + +- `<image-name>` (Same as using `<image-name>` with the `latest` tag) +- `<image-name>:<tag>` +- `<image-name>@<digest>` + +**Example of `services`**: ```yaml -pages: - stage: deploy +default: + image: + name: ruby:2.6 + entrypoint: ["/bin/bash"] + + services: + - name: my-postgres:11.7 + alias: db-postgres + entrypoint: ["/usr/local/bin/db-postgres"] + command: ["start"] + + before_script: + - bundle install + +test: script: - - mkdir .public - - cp -r * .public - - mv .public public - artifacts: - paths: - - public - rules: - - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + - bundle exec rake spec ``` -This example moves all files from the root of the project to the `public/` directory. -The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop. +In this example, the job launches a Ruby container. Then, from that container, the job launches +another container that's running PostgreSQL. Then the job then runs scripts +in that container. + +**Related topics**: + +- [Available settings for `services`](../services/index.md#available-settings-for-services). +- [Define `services` in the `.gitlab-ci.yml` file](../services/index.md#define-services-in-the-gitlab-ciyml-file). +- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). +- [Use Docker to build Docker images](../docker/using_docker_build.md). + +### `stage` + +Use `stage` to define which [stage](#stages) a job runs in. Jobs in the same +`stage` can execute in parallel (see **Additional details**). + +If `stage` is not defined, the job uses the `test` stage by default. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: An array including any number of stage names. Stage names can be: + +- The [default stages](#stages). +- User-defined stages. + +**Example of `stage`**: + +```yaml +stages: + - build + - test + - deploy + +job1: + stage: build + script: + - echo "This job compiles code." + +job2: + stage: test + script: + - echo "This job tests the compiled code. It runs when the build stage completes." + +job3: + script: + - echo "This job also runs in the test stage". + +job4: + stage: deploy + script: + - echo "This job deploys the code. It runs when the test stage completes." +``` **Additional details**: -You must: +- Jobs can run in parallel if they run on different runners. +- If you have only one runner, jobs can run in parallel if the runner's + [`concurrent` setting](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section) + is greater than `1`. -- Place any static content in a `public/` directory. -- Define [`artifacts`](#artifacts) with a path to the `public/` directory. +#### `stage: .pre` -### `inherit` +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9. +Use the `.pre` stage to make a job run at the start of a pipeline. `.pre` is +always the first stage in a pipeline. User-defined stages execute after `.pre`. +You do not have to define `.pre` in [`stages`](#stages). -Use `inherit:` to [control inheritance of globally-defined defaults and variables](../jobs/index.md#control-the-inheritance-of-default-keywords-and-global-variables). +You must have a job in at least one stage other than `.pre` or `.post`. -#### `inherit:default` +**Keyword type**: You can only use it with a job's `stage` keyword. -Use `inherit:default` to control the inheritance of [default keywords](#default). +**Example of `stage: .pre`**: -**Keyword type**: Job keyword. You can use it only as part of a job. +```yaml +stages: + - build + - test -**Possible inputs**: +job1: + stage: build + script: + - echo "This job runs in the build stage." -- `true` (default) or `false` to enable or disable the inheritance of all default keywords. -- A list of specific default keywords to inherit. +first-job: + stage: .pre + script: + - echo "This job runs in the .pre stage, before all other stages." + +job2: + stage: test + script: + - echo "This job runs in the test stage." +``` + +#### `stage: .post` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4. -**Example of `inherit:default`:** +Use the `.post` stage to make a job run at the end of a pipeline. `.post` +is always the last stage in a pipeline. User-defined stages execute before `.post`. +You do not have to define `.post` in [`stages`](#stages). + +You must have a job in at least one stage other than `.pre` or `.post`. + +**Keyword type**: You can only use it with a job's `stage` keyword. + +**Example of `stage: .post`**: ```yaml -default: - retry: 2 - image: ruby:3.0 - interruptible: true +stages: + - build + - test job1: - script: echo "This job does not inherit any default keywords." - inherit: - default: false + stage: build + script: + - echo "This job runs in the build stage." + +last-job: + stage: .post + script: + - echo "This job runs in the .post stage, after all other stages." job2: - script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'." - inherit: - default: - - retry - - image + stage: test + script: + - echo "This job runs in the test stage." ``` -**Additional details:** +### `tags` -- You can also list default keywords to inherit on one line: `default: [keyword1, keyword2]` +> - A limit of 50 tags per job [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338929) in GitLab 14.3. +> - A limit of 50 tags per job [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/339855) in GitLab 14.3. -#### `inherit:variables` +Use `tags` to select a specific runner from the list of all runners that are +available for the project. -Use `inherit:variables` to control the inheritance of [global variables](#variables) keywords. +When you register a runner, you can specify the runner's tags, for +example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner must +be assigned every tag listed in the job. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). + +**Possible inputs**: + +- An array of tag names. +- [CI/CD variables](../runners/configure_runners.md#use-cicd-variables-in-tags) in GitLab 14.1 and later. + +**Example of `tags`**: + +```yaml +job: + tags: + - ruby + - postgres +``` + +In this example, only runners with *both* the `ruby` and `postgres` tags can run the job. + +**Additional details**: + +- In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later, + the number of tags must be less than `50`. + +**Related topics**: + +- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run). + +### `timeout` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3. + +Use `timeout` to configure a timeout for a specific job. If the job runs for longer +than the timeout, the job fails. + +The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run). +but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). + +**Possible inputs**: A period of time written in natural language. For example, these are all equivalent: + +- `3600 seconds` +- `60 minutes` +- `one hour` + +**Example of `timeout`**: + +```yaml +build: + script: build.sh + timeout: 3 hours 30 minutes + +test: + script: rspec + timeout: 3h 30m +``` + +### `trigger` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in GitLab Premium 11.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. + +Use `trigger` to start a downstream pipeline that is either: + +- [A multi-project pipeline](../pipelines/multi_project_pipelines.md). +- [A child pipeline](../pipelines/parent_child_pipelines.md). **Keyword type**: Job keyword. You can use it only as part of a job. **Possible inputs**: -- `true` (default) or `false` to enable or disable the inheritance of all global variables. -- A list of specific variables to inherit. +- For multi-project pipelines, path to the downstream project. +- For child pipelines, path to the child pipeline CI/CD configuration file. -**Example of `inherit:variables`:** +**Example of `trigger` for multi-project pipeline**: ```yaml -variables: - VARIABLE1: "This is variable 1" - VARIABLE2: "This is variable 2" - VARIABLE3: "This is variable 3" +rspec: + stage: test + script: bundle exec rspec -job1: - script: echo "This job does not inherit any global variables." - inherit: - variables: false +staging: + stage: deploy + trigger: my/deployment +``` -job2: - script: echo "This job inherits only the two listed global variables. It does not inherit 'VARIABLE3'." - inherit: - variables: - - VARIABLE1 - - VARIABLE2 +**Example of `trigger` for child pipelines**: + +```yaml +trigger_job: + trigger: + include: path/to/child-pipeline.yml ``` -**Additional details:** +**Additional details**: -- You can also list global variables to inherit on one line: `variables: [VARIABLE1, VARIABLE2]` +- Jobs with `trigger` can only use a [limited set of keywords](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file). + For example, you can't run commands with [`script`](#script), [`before_script`](#before_script), + or [`after_script`](#after_script). +- You [cannot use the API to start `when:manual` trigger jobs](https://gitlab.com/gitlab-org/gitlab/-/issues/284086). +- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you + can use [`when:manual`](#when) in the same job as `trigger`. In GitLab 13.4 and + earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. +- In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can + view which job triggered a downstream pipeline in the [pipeline graph](../pipelines/index.md#visualize-pipelines). + +**Related topics**: + +- [Multi-project pipeline configuration examples](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file). +- [Child pipeline configuration examples](../pipelines/parent_child_pipelines.md#examples). +- To run a pipeline for a specific branch, tag, or commit, you can use a [trigger token](../triggers/index.md) + to authenticate with the [pipeline triggers API](../../api/pipeline_triggers.md). + The trigger token is different than the `trigger` keyword. + +#### `trigger:strategy` + +Use `trigger:strategy` to force the `trigger` job to wait for the downstream pipeline to complete +before it is marked as **success**. + +This behavior is different than the default, which is for the `trigger` job to be marked as +**success** as soon as the downstream pipeline is created. + +This setting makes your pipeline execution linear rather than parallel. + +**Example of `trigger:strategy`**: + +```yaml +trigger_job: + trigger: + include: path/to/child-pipeline.yml + strategy: depend +``` + +In this example, jobs from subsequent stages wait for the triggered pipeline to +successfully complete before starting. -## `variables` +### `variables` [CI/CD variables](../variables/index.md) are configurable values that are passed to jobs. Use `variables` to create [custom variables](../variables/index.md#custom-cicd-variables). @@ -4071,10 +3689,11 @@ variable defined, the [job-level variable takes precedence](../variables/index.m **Possible inputs**: Variable name and value pairs: -- The name can use only numbers, letters, and underscores (`_`). +- The name can use only numbers, letters, and underscores (`_`). In some shells, + the first character must be a letter. - The value must be a string. -**Examples of `variables`:** +**Examples of `variables`**: ```yaml variables: @@ -4106,7 +3725,7 @@ deploy_review_job: automatically creates and makes available in the job. - You can [configure runner behavior with variables](../runners/configure_runners.md#configure-runner-behavior-with-variables). -### `variables:description` +#### `variables:description` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. @@ -4117,7 +3736,9 @@ Must be used with `value`, for the variable value. **Keyword type**: Global keyword. You cannot set job-level variables to be pre-filled when you run a pipeline manually. -**Possible inputs**: A string. +**Possible inputs**: + +- A string. **Example of `variables:description`**: @@ -4128,6 +3749,84 @@ variables: description: "The deployment target. Change this variable to 'canary' or 'production' if needed." ``` +### `when` + +Use `when` to configure the conditions for when jobs run. If not defined in a job, +the default value is `when: on_success`. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- `on_success` (default): Run the job only when all jobs in earlier stages succeed + or have `allow_failure: true`. +- `manual`: Run the job only when [triggered manually](../jobs/job_control.md#create-a-job-that-must-be-run-manually). +- `always`: Run the job regardless of the status of jobs in earlier stages. +- `on_failure`: Run the job only when at least one job in an earlier stage fails. +- `delayed`: [Delay the execution of a job](../jobs/job_control.md#run-a-job-after-a-delay) + for a specified duration. +- `never`: Don't run the job. + +**Example of `when`**: + +```yaml +stages: + - build + - cleanup_build + - test + - deploy + - cleanup + +build_job: + stage: build + script: + - make build + +cleanup_build_job: + stage: cleanup_build + script: + - cleanup build when failed + when: on_failure + +test_job: + stage: test + script: + - make test + +deploy_job: + stage: deploy + script: + - make deploy + when: manual + +cleanup_job: + stage: cleanup + script: + - cleanup after jobs + when: always +``` + +In this example, the script: + +1. Executes `cleanup_build_job` only when `build_job` fails. +1. Always executes `cleanup_job` as the last step in pipeline regardless of + success or failure. +1. Executes `deploy_job` when you run it manually in the GitLab UI. + +**Additional details**: + +- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you + can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and + earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. +- The default behavior of `allow_failure` changes to `true` with `when: manual`. + However, if you use `when: manual` with [`rules`](#rules), `allow_failure` defaults + to `false`. + +**Related topics**: + +- `when` can be used with [`rules`](#rules) for more dynamic job control. +- `when` can be used with [`workflow`](#workflow) to control when a pipeline can start. + ## Deprecated keywords The following keywords are deprecated. @@ -4150,7 +3849,7 @@ Defining `image`, `services`, `cache`, `before_script`, and `after_script` globally is deprecated. Support could be removed from a future release. -Use [`default:`](#default) instead. For example: +Use [`default`](#default) instead. For example: ```yaml default: |