diff options
Diffstat (limited to 'doc/ci/yaml/index.md')
| -rw-r--r-- | doc/ci/yaml/index.md | 204 |
1 files changed, 149 insertions, 55 deletions
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index eb587db6d5f..912eca364c9 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -175,6 +175,8 @@ Use `include:local` instead of symbolic links. - The YAML file must have the extension `.yml` or `.yaml`. - You can [use `*` and `**` wildcards in the file path](includes.md#use-includelocal-with-wildcard-file-paths). +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `include:local`**: ```yaml @@ -209,6 +211,8 @@ use `include:file`. You can use `include:file` in combination with `include:proj - A full path, relative to the root directory (`/`). The YAML file must have the extension `.yml` or `.yaml`. +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `include:file`**: ```yaml @@ -226,7 +230,7 @@ include: file: '/templates/.gitlab-ci-template.yml' - project: 'my-group/my-project' - ref: v1.0.0 + ref: v1.0.0 # Git Tag file: '/templates/.gitlab-ci-template.yml' - project: 'my-group/my-project' @@ -267,6 +271,8 @@ Use `include:remote` with a full URL to include a file from a different location - 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`. +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `include:remote`**: ```yaml @@ -292,6 +298,8 @@ Use `include:template` to include [`.gitlab-ci.yml` templates](https://gitlab.co - [`.gitlab-ci.yml` templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `include:template`**: ```yaml @@ -331,6 +339,11 @@ The order of the items in `stages` defines the execution order for jobs: - Jobs in the same stage run in parallel. - Jobs in the next stage run after the jobs from the previous stage complete successfully. +If a pipeline contains only jobs in the `.pre` or `.post` stages, it does not run. +There must be at least one other job in a different stage. `.pre` and `.post` stages +can be used in [required pipeline configuration](../../user/admin_area/settings/continuous_integration.md#required-pipeline-configuration) +to define compliance jobs that must run before or after project pipeline jobs. + **Keyword type**: Global keyword. **Example of `stages`**: @@ -504,6 +517,8 @@ 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). +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `after_script`**: ```yaml @@ -809,8 +824,8 @@ If not defined, the default name is `artifacts`, which becomes `artifacts.zip` w **Possible inputs**: -- The name of the artifacts archive. Can use [CI/CD variables](../variables/index.md). Must be combined with - [`artifacts:paths`](#artifactspaths). +- The name of the artifacts archive. CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + Must be combined with [`artifacts:paths`](#artifactspaths). **Example of `artifacts:name`**: @@ -977,7 +992,7 @@ failure. - `on_success` (default): Upload artifacts only when the job succeeds. - `on_failure`: Upload artifacts only when the job fails. - `always`: Always upload artifacts (except when jobs time out). For example, when - [uploading artifacts](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab) + [uploading artifacts](../testing/unit_test_reports.md#view-junit-screenshots-on-gitlab) required to troubleshoot failing tests. **Example of `artifacts:when`**: @@ -1002,6 +1017,8 @@ Use `before_script` to define an array of commands that should run before each j - Long commands [split over multiple lines](script.md#split-long-commands). - [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `before_script`**: ```yaml @@ -1016,6 +1033,7 @@ job: - 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. +- Using `before_script` at the top level, but not in the `default` section, [is deprecated](#globally-defined-image-services-cache-before_script-after_script). **Related topics**: @@ -1087,7 +1105,7 @@ no `cache:key` share the `default` cache. **Possible inputs**: - A string. -- A [predefined variables](../variables/index.md). +- A predefined [CI/CD variable](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). - A combination of both. **Example of `cache:key`**: @@ -1504,7 +1522,8 @@ Common environment names are `qa`, `staging`, and `production`, but you can use formats: - Plain text, including letters, digits, spaces, and these characters: `-`, `_`, `/`, `$`, `{`, `}`. -- CI/CD variables, including predefined, project, group, instance, or variables defined in the +- [CI/CD variables](../variables/where_variables_can_be_used.md#gitlab-ciyml-file), + including predefined, project, group, instance, or variables defined in the `.gitlab-ci.yml` file. You can't use variables defined in a `script` section. **Example of `environment:name`**: @@ -1526,7 +1545,8 @@ Set a URL for an [environment](../environments/index.md). **Possible inputs**: A single URL, in one of these formats: - Plain text, like `https://prod.example.com`. -- CI/CD variables, including predefined, project, group, instance, or variables defined in the +- [CI/CD variables](../variables/where_variables_can_be_used.md#gitlab-ciyml-file), + including predefined, project, group, instance, or variables defined in the `.gitlab-ci.yml` file. You can't use variables defined in a `script` section. **Example of `environment:url`**: @@ -1788,6 +1808,8 @@ Use `image` to specify a Docker image that the job runs in. - `<image-name>:<tag>` - `<image-name>@<digest>` +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `image`**: ```yaml @@ -1861,6 +1883,52 @@ image: - [Override the entrypoint of an image](../docker/using_docker_images.md#override-the-entrypoint-of-an-image). +#### `image:pull_policy` + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default. +> - Requires GitLab Runner 15.1 or later. + +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 `ci_docker_image_pull_policy`. +The feature is not ready for production use. + +The pull policy that the runner uses to fetch the Docker image. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the [`default` section](#default). + +**Possible inputs**: + +- A single pull policy, or multiple pull policies in an array. + Can be `always`, `if-not-present`, or `never`. + +**Examples of `image:pull_policy`**: + +```yaml +job1: + script: echo "A single pull policy." + image: + name: ruby:3.0 + pull_policy: if-not-present + +job2: + script: echo "Multiple pull policies." + image: + name: ruby:3.0 + pull_policy: [always, if-not-present] +``` + +**Additional details**: + +- If the runner does not support the defined pull policy, the job fails with an error similar to: + `ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never])`. + +**Related topics**: + +- [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). +- [How runner pull policies work](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work). +- [Using multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#using-multiple-pull-policies). + ### `inherit` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9. @@ -1945,9 +2013,9 @@ job2: 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. +This keyword has no effect if [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) +is disabled. When enabled, a running job with `interruptible: true` is cancelled when +starting a pipeline for a new change on the same branch. You can't cancel subsequent jobs after a job with `interruptible: false` starts. @@ -2169,8 +2237,8 @@ build_job: 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: +In GitLab 13.3 and later, you can use [CI/CD variables](../variables/where_variables_can_be_used.md#gitlab-ciyml-file) +in `needs:project`, for example: ```yaml build_job: @@ -2268,43 +2336,58 @@ can use that variable in `needs:pipeline` to download artifacts from the parent To need a job that sometimes does not exist in the pipeline, add `optional: true` to the `needs` configuration. If not defined, `optional: false` is the default. -Jobs that use [`rules`](#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: +Jobs that use [`rules`](#rules), [`only`, or `except`](#only--except) might not always +be added to a pipeline. GitLab checks the `needs` relationships before starting a +pipeline: -- `'job1' job needs 'job2' job, but it was not added to the pipeline` +- If the needs entry has `optional: true` and the needed job is present in the pipeline, + the job waits for it to complete before starting. +- If the needed job is not present, the job can start when all other needs requirements are met. +- If the `needs` section contains only optional jobs, and none are added to the pipeline, + the job starts immediately (the same as an empty `needs` entry: `needs: []`). +- If a needed job has `optional: false`, but it was not added to the pipeline, the + pipeline fails to start with an error similar to: `'job1' job needs 'job2' job, but it was not added to the pipeline`. **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: - -- `job`: The job to make optional. -- `true` or `false` (default). - **Example of `needs:optional`**: ```yaml -build: +build-job: stage: build + +test-job1: + stage: test + +test-job2: + stage: test rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH -rspec: - stage: test +deploy-job: + stage: deploy needs: - - job: build + - job: test-job2 + optional: true + - job: test-job1 + +review-job: + stage: deploy + needs: + - job: test-job2 optional: true ``` In this example: -- 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. +- `build-job`, `test-job1`, and `test-job2` start in stage order. +- When the branch is the default branch, `test-job2` is added to the pipeline, so: + - `deploy-job` waits for both `test-job1` and `test-job2` to complete. + - `review-job` waits for `test-job2` to complete. +- When the branch is not the default branch, `test-job2` is not added to the pipeline, so: + - `deploy-job` waits for only `test-job1` to complete, and does not wait for the missing `test-job2`. + - `review-job` has no other needed jobs and starts immediately (at the same time as `build-job`), + like `needs: []`. #### `needs:pipeline` @@ -2735,7 +2818,7 @@ This example creates a release: **Related topics**: -- [CI/CD example of the `release` keyword](../../user/project/releases/index.md#cicd-example-of-the-release-keyword). +- [CI/CD example of the `release` keyword](../../user/project/releases/index.md#creating-a-release-by-using-a-cicd-job). - [Create multiple releases in a single pipeline](../../user/project/releases/index.md#create-multiple-releases-in-a-single-pipeline). - [Use a custom SSL CA certificate authority](../../user/project/releases/index.md#use-a-custom-ssl-ca-certificate-authority). @@ -2750,7 +2833,9 @@ New tags use the SHA associated with the pipeline. **Possible inputs**: -- A tag name. Can use [CI/CD variables](../variables/index.md). +- A tag name. + +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). **Example of `release:tag_name`**: @@ -2899,7 +2984,7 @@ can be deployed to, but only one deployment can occur per device at any given ti **Possible inputs**: - Only letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. - It can't start or end with `/`. + It can't start or end with `/`. CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). **Example of `resource_group`**: @@ -3177,8 +3262,9 @@ job: 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. + In other words, `exists` always reports `true` if more than 10,000 checks + run. Repositories with less than 10,000 files might still be impacted if the `exists` + rules are checked more than 10,000 times. - `exists` resolves to `true` if any of the listed files are found (an `OR` operation). #### `rules:allow_failure` @@ -3262,6 +3348,8 @@ All jobs except [trigger jobs](#trigger) require a `script` keyword. - Long commands [split over multiple lines](script.md#split-long-commands). - [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `script`**: ```yaml @@ -3396,6 +3484,8 @@ to the image specified in the [`image`](#image) keyword. - `<image-name>:<tag>` - `<image-name>@<digest>` +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file), but [not for `alias`](https://gitlab.com/gitlab-org/gitlab/-/issues/19561). + **Example of `services`**: ```yaml @@ -3486,7 +3576,8 @@ 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). -You must have a job in at least one stage other than `.pre` or `.post`. +If a pipeline contains only jobs in the `.pre` or `.post` stages, it does not run. +There must be at least one other job in a different stage. **Keyword type**: You can only use it with a job's `stage` keyword. @@ -3521,7 +3612,8 @@ 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`. +If a pipeline contains only jobs in the `.pre` or `.post` stages, it does not run. +There must be at least one other job in a different stage. **Keyword type**: You can only use it with a job's `stage` keyword. @@ -3566,7 +3658,8 @@ be assigned every tag listed in the job. **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. +- CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file) + in GitLab 14.1 and later. **Example of `tags`**: @@ -3705,12 +3798,9 @@ successfully complete before starting. #### `trigger:forward` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213729) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `ci_trigger_forward_variables`. Disabled by default. - -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 `ci_trigger_forward_variables`. -The feature is not ready for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213729) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `ci_trigger_forward_variables`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/355572) in GitLab 14.10. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/355572) in GitLab 15.1. [Feature flag `ci_trigger_forward_variables`](https://gitlab.com/gitlab-org/gitlab/-/issues/355572) removed. Use `trigger:forward` to specify what to forward to the downstream pipeline. You can control what is forwarded to both [parent-child pipelines](../pipelines/parent_child_pipelines.md) @@ -3779,6 +3869,8 @@ variable defined, the [job-level variable takes precedence](../variables/index.m the first character must be a letter. - The value must be a string. +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Examples of `variables`**: ```yaml @@ -3844,18 +3936,18 @@ variables: 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. +**Keyword type**: Job keyword. You can use it as part of a job. `when: always` and `when: never` can also be used in [`workflow:rules`](#workflow). **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. +- `always`: Run the job regardless of the status of jobs in earlier stages. Can also be used in `workflow:rules`. - `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. +- `never`: Don't run the job. Can only be used in a [`rules`](#rules) section or `workflow: rules`. **Example of `when`**: @@ -3921,18 +4013,20 @@ In this example, the script: The following keywords are deprecated. -### Globally-defined `types` +<!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> -WARNING: -`types` is deprecated, and is [scheduled to be removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/346823). +### Globally-defined `types` (removed) + +The `types` keyword was deprecated in GitLab 9.0, and [removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/346823). Use [`stages`](#stages) instead. -### Job-defined `type` +### Job-defined `type` (removed) -WARNING: -`type` is deprecated, and is [scheduled to be removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/346823). +The `type` keyword was deprecated in GitLab 9.0, and [removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/346823). Use [`stage`](#stage) instead. +<!--- end_remove --> + ### Globally-defined `image`, `services`, `cache`, `before_script`, `after_script` Defining `image`, `services`, `cache`, `before_script`, and |