Skip to content

G
gitlab-ce
Commit 4fa9ffec authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Marcel Amirault
Browse files
Options

Edited for style and consistency 

Related to: https://gitlab.com/groups/gitlab-org/-/epics/4138
parent 26b813ce
Hide whitespace changes
Inline Side-by-side
Showing with 218 additions and 226 deletions
doc/ci/yaml/README.md
View file @ 4fa9ffec
...@@ -46,7 +46,7 @@ The keywords available for jobs are: ...@@ -46,7 +46,7 @@ The keywords available for jobs are:
| [`only`](#onlyexcept-basic) | Limit when jobs are created. | | [`only`](#onlyexcept-basic) | Limit when jobs are created. |
| [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. |
| [`parallel`](#parallel) | How many instances of a job should be run in parallel. | | [`parallel`](#parallel) | How many instances of a job should be run in parallel. |
| [`release`](#release) | Instructs the runner to generate a [Release](../../user/project/releases/index.md) object. | | [`release`](#release) | Instructs the runner to generate a [release](../../user/project/releases/index.md) object. |
| [`resource_group`](#resource_group) | Limit job concurrency. | | [`resource_group`](#resource_group) | Limit job concurrency. |
| [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. | | [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. |
| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. | | [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. |
...@@ -79,7 +79,7 @@ You can't use these keywords as job names: ...@@ -79,7 +79,7 @@ You can't use these keywords as job names:
You can set global defaults for some keywords. Jobs that do not define one or more 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.
The following job keywords can be defined inside a `default:` section: These job keywords can be defined inside a `default:` section:
- [`after_script`](#after_script) - [`after_script`](#after_script)
- [`artifacts`](#artifacts) - [`artifacts`](#artifacts)
...@@ -92,7 +92,7 @@ The following job keywords can be defined inside a `default:` section: ...@@ -92,7 +92,7 @@ The following job keywords can be defined inside a `default:` section:
- [`tags`](#tags) - [`tags`](#tags)
- [`timeout`](#timeout) - [`timeout`](#timeout)
This example sets the `ruby:2.5` image as the default for all jobs in the pipeline. The following example sets the `ruby:2.5` image as the default for all jobs in the pipeline.
The `rspec 2.6` job does not use the default, because it overrides the default with The `rspec 2.6` job does not use the default, because it overrides the default with
a job-specific `image:` section: a job-specific `image:` section:
...@@ -159,9 +159,9 @@ the [`needs`](#needs) keyword. ...@@ -159,9 +159,9 @@ the [`needs`](#needs) keyword.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5
The top-level `workflow:` keyword determines whether or not a pipeline is created. Use `workflow:` to determine whether or not a pipeline is created.
It accepts a single `rules:` keyword that is similar to [`rules:` defined in jobs](#rules). Define this keyword at the top level, with a single `rules:` keyword that
Use it to define what can trigger a new pipeline. is similar to [`rules:` defined in jobs](#rules).
You can use the [`workflow:rules` templates](#workflowrules-templates) to import You can use the [`workflow:rules` templates](#workflowrules-templates) to import
a preconfigured `workflow: rules` entry. a preconfigured `workflow: rules` entry.
...@@ -186,7 +186,7 @@ Some example `if` clauses for `workflow: rules`: ...@@ -186,7 +186,7 @@ Some example `if` clauses for `workflow: rules`:
See the [common `if` clauses for `rules`](#common-if-clauses-for-rules) for more examples. See the [common `if` clauses for `rules`](#common-if-clauses-for-rules) for more examples.
For example, in the following configuration, pipelines run for all `push` events (changes to In the following example, pipelines run for all `push` events (changes to
branches and new tags). Pipelines for push events with `-draft` in the commit message branches and new tags). Pipelines for push events with `-draft` in the commit message
don't run, because they are set to `when: never`. Pipelines for schedules or merge requests don't run, because they are set to `when: never`. Pipelines for schedules or merge requests
don't run either, because no rules evaluate to true for them: don't run either, because no rules evaluate to true for them:
...@@ -226,7 +226,7 @@ If your rules match both branch pipelines and merge request pipelines, ...@@ -226,7 +226,7 @@ If your rules match both branch pipelines and merge request pipelines,
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0.
We provide templates that set up `workflow: rules` GitLab provides templates that set up `workflow: rules`
for common scenarios. These templates help prevent duplicate pipelines. for common scenarios. These templates help prevent duplicate pipelines.
The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml) The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)
...@@ -234,12 +234,12 @@ makes your pipelines run for branches and tags. ...@@ -234,12 +234,12 @@ makes your pipelines run for branches and tags.
Branch pipeline status is displayed in merge requests that use the branch Branch pipeline status is displayed in merge requests that use the branch
as a source. However, this pipeline type does not support any features offered by as a source. However, this pipeline type does not support any features offered by
[Merge Request Pipelines](../merge_request_pipelines/), like [merge request pipelines](../merge_request_pipelines/), like
[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results) [pipelines for merge results](../merge_request_pipelines/#pipelines-for-merged-results)
or [Merge Trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/). or [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/).
Use this template if you are intentionally avoiding those features. This template intentionally avoids those features.
It is [included](#include) as follows: To [include](#include) it:
```yaml ```yaml
include: include:
...@@ -249,10 +249,9 @@ include: ...@@ -249,10 +249,9 @@ include:
The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml) The [`MergeRequest-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/MergeRequest-Pipelines.gitlab-ci.yml)
makes your pipelines run for the default branch, tags, and makes your pipelines run for the default branch, tags, and
all types of merge request pipelines. Use this template if you use any of the all types of merge request pipelines. Use this template if you use any of the
the [Pipelines for Merge Requests features](../merge_request_pipelines/), as mentioned the [pipelines for merge requests features](../merge_request_pipelines/).
above.
It is [included](#include) as follows: To [include](#include) it:
```yaml ```yaml
include: include:
...@@ -317,7 +316,7 @@ does not block triggered pipelines. ...@@ -317,7 +316,7 @@ does not block triggered pipelines.
> - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later. > - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later.
> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4.
Use the `include` keyword to include external YAML files in your CI/CD configuration. Use `include` to include external YAML files in your CI/CD configuration.
You can break down one long `gitlab-ci.yml` file into multiple files to increase readability, You can break down one long `gitlab-ci.yml` file into multiple files to increase readability,
or reduce duplication of the same configuration in multiple places. or reduce duplication of the same configuration in multiple places.
...@@ -339,11 +338,11 @@ YAML files, use [`!reference` tags](#reference-tags) or the [`extends` keyword]( ...@@ -339,11 +338,11 @@ YAML files, use [`!reference` tags](#reference-tags) or the [`extends` keyword](
| [`remote`](#includeremote) | Include a file from a remote URL. Must be publicly accessible. | | [`remote`](#includeremote) | Include a file from a remote URL. Must be publicly accessible. |
| [`template`](#includetemplate) | Include templates that are provided by GitLab. | | [`template`](#includetemplate) | Include templates that are provided by GitLab. |
The `.gitlab-ci.yml` file configuration included by all methods is evaluated when the pipeline is created. When the pipeline starts, the `.gitlab-ci.yml` file configuration included by all methods is evaluated.
The configuration is a snapshot in time and persisted in the database. Any changes to The configuration is a snapshot in time and persists in the database. GitLab does not reflect any changes to
the referenced `.gitlab-ci.yml` file configuration is not reflected in GitLab until the next pipeline is created. the referenced `.gitlab-ci.yml` file configuration until the next pipeline starts.
The files defined by `include` are: The `include` files are:
- Deep merged with those in the `.gitlab-ci.yml` file. - Deep merged with those in the `.gitlab-ci.yml` file.
- Always evaluated first and merged with the content of the `.gitlab-ci.yml` file, - Always evaluated first and merged with the content of the `.gitlab-ci.yml` file,
...@@ -367,13 +366,13 @@ include: ...@@ -367,13 +366,13 @@ include:
file: '.compliance-gitlab-ci.yml' file: '.compliance-gitlab-ci.yml'
``` ```
For an example of how you can include these predefined variables, and their impact on CI jobs, For an example of how you can include these predefined variables, and the variables' impact on CI/CD jobs,
see the following [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos). see this [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos).
#### `include:local` #### `include:local`
`include:local` includes a file that is in the same repository as the `.gitlab-ci.yml` file. Use `include:local` to include a file that is in the same repository as the `.gitlab-ci.yml` file.
It's referenced with full paths relative to the root directory (`/`). Use a full path relative to the root directory (`/`).
If you use `include:local`, make sure that both the `.gitlab-ci.yml` file and the local file If you use `include:local`, make sure that both the `.gitlab-ci.yml` file and the local file
are on the same branch. are on the same branch.
...@@ -390,7 +389,7 @@ include: ...@@ -390,7 +389,7 @@ include:
- local: '/templates/.gitlab-ci-template.yml' - local: '/templates/.gitlab-ci-template.yml'
``` ```
This can be defined as a short local include: You can also use shorter syntax to define the path:
```yaml ```yaml
include: '.gitlab-ci-production.yml' include: '.gitlab-ci-production.yml'
...@@ -404,8 +403,9 @@ Use local includes instead of symbolic links. ...@@ -404,8 +403,9 @@ Use local includes instead of symbolic links.
To include files from another private project on the same GitLab instance, To include files from another private project on the same GitLab instance,
use `include:file`. You can use `include:file` in combination with `include:project` only. use `include:file`. You can use `include:file` in combination with `include:project` only.
Use a full path, relative to the root directory (`/`).
The included file is referenced with a full path, relative to the root directory (`/`). For example: For example:
```yaml ```yaml
include: include:
...@@ -413,7 +413,7 @@ include: ...@@ -413,7 +413,7 @@ include:
file: '/templates/.gitlab-ci-template.yml' file: '/templates/.gitlab-ci-template.yml'
``` ```
You can also specify a `ref`. If not specified, it defaults to the `HEAD` of the project: You can also specify a `ref`. If you do not specify a value, the ref defaults to the `HEAD` of the project:
```yaml ```yaml
include: include:
...@@ -502,15 +502,15 @@ to resolve all files is 30 seconds. ...@@ -502,15 +502,15 @@ to resolve all files is 30 seconds.
#### Additional `includes` examples #### Additional `includes` examples
There is a list of [additional `includes` examples](includes.md) available. View [additional `includes` examples](includes.md).
## Keyword details ## Keyword details
The following are detailed explanations for keywords used to configure CI/CD pipelines. The following topics explain how to use keywords to configure CI/CD pipelines.
### `image` ### `image`
Used to specify [a Docker image](../docker/using_docker_images.md#what-is-an-image) to use for the job. Use `image` to specify [a Docker image](../docker/using_docker_images.md#what-is-an-image) to use for the job.
For: For:
...@@ -531,13 +531,13 @@ For more information, see [Available settings for `image`](../docker/using_docke ...@@ -531,13 +531,13 @@ For more information, see [Available settings for `image`](../docker/using_docke
#### `services` #### `services`
Used to specify a [service Docker image](../docker/using_docker_images.md#what-is-a-service), linked to a base image specified in [`image`](#image). Use `services` to specify a [service Docker image](../docker/using_docker_images.md#what-is-a-service), linked to a base image specified in [`image`](#image).
For: For:
- Usage examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml). - Usage examples, see [Define `image` and `services` from `.gitlab-ci.yml`](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml).
- Detailed usage information, refer to [Docker integration](../docker/index.md) documentation. - Detailed usage information, refer to [Docker integration](../docker/index.md) documentation.
- For example services, see [GitLab CI/CD Services](../services/index.md). - Example services, see [GitLab CI/CD Services](../services/index.md).
##### `services:name` ##### `services:name`
...@@ -565,8 +565,11 @@ For more information, see [Available settings for `services`](../docker/using_do ...@@ -565,8 +565,11 @@ For more information, see [Available settings for `services`](../docker/using_do
### `script` ### `script`
`script` is the only required keyword that a job needs. It's a shell script Use `script` to specify a shell script for the runner to execute.
that is executed by the runner. For example:
All jobs except [trigger jobs](#trigger) require a `script` keyword.
For example:
```yaml ```yaml
job: job:
...@@ -575,7 +578,7 @@ job: ...@@ -575,7 +578,7 @@ job:
You can use [YAML anchors with `script`](#yaml-anchors-for-scripts). You can use [YAML anchors with `script`](#yaml-anchors-for-scripts).
This keyword can also contain several commands in an array: The `script` keyword can also contain several commands in an array:
```yaml ```yaml
job: job:
...@@ -609,7 +612,7 @@ job: ...@@ -609,7 +612,7 @@ job:
You can verify the syntax is valid with the [CI Lint](../lint.md) tool. You can verify the syntax is valid with the [CI Lint](../lint.md) tool.
Be careful when using these special characters as well: Be careful when using these characters as well:
- `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``. - `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
...@@ -629,10 +632,10 @@ job: ...@@ -629,10 +632,10 @@ job:
Use `before_script` to define an array of commands that should run before each job, Use `before_script` to define an array of commands that should run before each job,
but after [artifacts](#artifacts) are restored. but after [artifacts](#artifacts) are restored.
Scripts specified in `before_script` are concatenated with any scripts specified Scripts you specify in `before_script` are concatenated with any scripts you specify
in the main [`script`](#script), and executed together in a single shell. in the main [`script`](#script). The combine scripts execute together in a single shell.
It's possible to overwrite a globally defined `before_script` if you define it in a job: You can overwrite a globally-defined `before_script` if you define it in a job:
```yaml ```yaml
default: default:
...@@ -657,11 +660,11 @@ You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts). ...@@ -657,11 +660,11 @@ You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts).
Use `after_script` to define an array of commands that run after each job, Use `after_script` to define an array of commands that run after each job,
including failed jobs. including failed jobs.
If a job times out or is cancelled, the `after_script` commands are not executed. If a job times out or is cancelled, the `after_script` commands do not execute.
Support for executing `after_script` commands for timed-out or cancelled jobs An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15603) exists to support
[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/15603). executing `after_script` commands for timed-out or cancelled jobs.
Scripts specified in `after_script` are executed in a new shell, separate from any Scripts you specify in `after_script` execute in a new shell, separate from any
`before_script` or `script` scripts. As a result, they: `before_script` or `script` scripts. As a result, they:
- Have a current working directory set back to the default. - Have a current working directory set back to the default.
...@@ -694,7 +697,7 @@ You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts). ...@@ -694,7 +697,7 @@ You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts).
#### Script syntax #### Script syntax
You can use special syntax in [`script`](README.md#script) sections to: You can use syntax in [`script`](README.md#script) sections to:
- [Split long commands](script.md#split-long-commands) into multiline commands. - [Split long commands](script.md#split-long-commands) into multiline commands.
- [Use color codes](script.md#add-color-codes-to-script-output) to make job logs easier to review. - [Use color codes](script.md#add-color-codes-to-script-output) to make job logs easier to review.
...@@ -703,9 +706,19 @@ You can use special syntax in [`script`](README.md#script) sections to: ...@@ -703,9 +706,19 @@ You can use special syntax in [`script`](README.md#script) sections to:
### `stage` ### `stage`
`stage` is defined per-job and relies on [`stages`](#stages), which is defined Use `stage` to define which stage a job runs in. Jobs in the same
globally. Use `stage` to define which stage a job runs in, and jobs of the same `stage` can execute in parallel (subject to [certain conditions](#use-your-own-runners)).
`stage` are executed in parallel (subject to [certain conditions](#use-your-own-runners)). For example:
Jobs without a `stage` entry use the `test` stage by default. If [`stages`](#stages)
is not defined in the pipeline, you can use the 5 default stages, which execute in
this order:
- [`.pre`](#pre-and-post)
- `build`
- `test`
- `deploy`
- [`.post`](#pre-and-post)
For example:
```yaml ```yaml
stages: stages:
...@@ -751,45 +764,39 @@ is greater than `1`. ...@@ -751,45 +764,39 @@ is greater than `1`.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31441) in GitLab 12.4.
The following stages are available to every pipeline: Use `pre` and `post` for jobs that need to run first or last in a pipeline.
- `.pre`, which is guaranteed to always be the first stage in a pipeline. - `.pre` is guaranteed to always be the first stage in a pipeline.
- `.post`, which is guaranteed to always be the last stage in a pipeline. - `.post` is guaranteed to always be the last stage in a pipeline.
User-defined stages are executed after `.pre` and before `.post`. User-defined stages are executed after `.pre` and before `.post`.
A pipeline is not created if all jobs are in `.pre` or `.post` stages. You must have a job in at least one stage other than `.pre` or `.post`.
The order of `.pre` and `.post` can't be changed, even if defined out of order in the `.gitlab-ci.yml` file.
For example, the following are equivalent configuration:
- Configured in order:
```yaml You can't change the order of `.pre` and `.post`, even if you define them out of order in the `.gitlab-ci.yml` file.
stages: For example, the following configurations are equivalent:
- .pre
- a
- b
- .post
```
- Configured out of order:
```yaml ```yaml
stages: stages:
- a - .pre
- .pre - a
- b - b
- .post - .post
``` ```
- Not explicitly configured: ```yaml
stages:
- a
- .pre
- b
- .post
```
```yaml ```yaml
stages: stages:
- a - a
- b - b
``` ```
### `extends` ### `extends`
...@@ -799,7 +806,7 @@ Use `extends` to reuse configuration sections. It's an alternative to [YAML anch ...@@ -799,7 +806,7 @@ Use `extends` to reuse configuration sections. It's an alternative to [YAML anch
and is a little more flexible and readable. You can use `extends` to reuse configuration and is a little more flexible and readable. You can use `extends` to reuse configuration
from [included configuration files](#use-extends-and-include-together). from [included configuration files](#use-extends-and-include-together).
In this example, the `rspec` job uses the configuration from the `.tests` template job. In the following example, the `rspec` job uses the configuration from the `.tests` template job.
GitLab: GitLab:
- Performs a reverse deep merge based on the keys. - Performs a reverse deep merge based on the keys.
...@@ -870,8 +877,8 @@ In GitLab 12.0 and later, it's also possible to use multiple parents for ...@@ -870,8 +877,8 @@ In GitLab 12.0 and later, it's also possible to use multiple parents for
#### Merge details #### Merge details
`extends` is able to merge hashes but not arrays. You can use `extends` to merge hashes but not arrays.
The algorithm used for merge is "closest scope wins", so The algorithm used for merge is "closest scope wins," so
keys from the last member always override anything defined on other keys from the last member always override anything defined on other
levels. For example: levels. For example:
...@@ -923,7 +930,7 @@ rspec: ...@@ -923,7 +930,7 @@ rspec:
- rake rspec - rake rspec
``` ```
Note that in the example above: In this example:
- The `variables` sections merge, but `URL: "http://docker-url.internal"` overwrites `URL: "http://my-url.internal"`. - The `variables` sections merge, but `URL: "http://docker-url.internal"` overwrites `URL: "http://my-url.internal"`.
- `tags: ['docker']` overwrites `tags: ['production']`. - `tags: ['docker']` overwrites `tags: ['production']`.
...@@ -935,8 +942,8 @@ Note that in the example above: ...@@ -935,8 +942,8 @@ Note that in the example above:
To reuse configuration from different configuration files, To reuse configuration from different configuration files,
combine `extends` and [`include`](#include). combine `extends` and [`include`](#include).
In this example, a `script` is defined in the `included.yml` file. In the following example, a `script` is defined in the `included.yml` file.
Then, in the `.gitlab-ci.yml` file, you use `extends` to refer Then, in the `.gitlab-ci.yml` file, `extends` refers
to the contents of the `script`: to the contents of the `script`:
- `included.yml`: - `included.yml`:
...@@ -961,11 +968,11 @@ to the contents of the `script`: ...@@ -961,11 +968,11 @@ to the contents of the `script`:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3.
Use the `rules` keyword to include or exclude jobs in pipelines. Use `rules` to include or exclude jobs in pipelines.
Rules are evaluated *in order* until the first match. When matched, the job Rules are 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. is either included or excluded from the pipeline, depending on the configuration.
If included, the job also has [certain attributes](#rules-attributes) The job can also have [certain attributes](#rules-attributes)
added to it. added to it.
`rules` replaces [`only/except`](#onlyexcept-basic) and they can't be used together `rules` replaces [`only/except`](#onlyexcept-basic) and they can't be used together
...@@ -1024,7 +1031,7 @@ The job is not added to the pipeline: ...@@ -1024,7 +1031,7 @@ The job is not added to the pipeline:
`when: always`. `when: always`.
- If a rule matches, and has `when: never` as the attribute. - If a rule matches, and has `when: never` as the attribute.
This example uses `if` to strictly limit when jobs run: The following example uses `if` to strictly limit when jobs run:
```yaml ```yaml
job: job:
...@@ -1101,7 +1108,7 @@ other pipelines, including **both** push (branch) and merge request pipelines. W ...@@ -1101,7 +1108,7 @@ other pipelines, including **both** push (branch) and merge request pipelines. W
this configuration, every push to an open merge request's source branch this configuration, every push to an open merge request's source branch
causes duplicated pipelines. causes duplicated pipelines.
There are multiple ways to avoid duplicate pipelines: To avoid duplicate pipelines, you can:
- Use [`workflow`](#workflow) to specify which types of pipelines - Use [`workflow`](#workflow) to specify which types of pipelines
can run. can run.
...@@ -1164,12 +1171,11 @@ runs in all cases except merge requests. ...@@ -1164,12 +1171,11 @@ runs in all cases except merge requests.
#### `rules:if` #### `rules:if`
`rules:if` clauses determine whether or not jobs are added to a pipeline by evaluating Use `rules:if` clauses to specify when to add a job to a pipeline:
an `if` statement. If the `if` statement is true, the job is either included
or excluded from a pipeline. In plain English, `if` rules can be interpreted as one of:
- "If this rule evaluates to true, add the job" (default). - If an `if` statement is true, add the job to the pipeline.
- "If this rule evaluates to true, do not add the job" (by adding `when: never`). - 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.
`rules:if` differs slightly from `only:variables` by accepting only a single `rules:if` differs slightly from `only:variables` by accepting only a single
expression string per rule, rather than an array of them. Any set of expressions to be expression string per rule, rather than an array of them. Any set of expressions to be
...@@ -1227,7 +1233,9 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: ...@@ -1227,7 +1233,9 @@ check the value of the `$CI_PIPELINE_SOURCE` variable:
| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. |
| `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). | | `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). |
For example: The following example runs the job as a manual job in scheduled pipelines or in push
pipelines (to branches or tags), with `when: on_success` (default). It does not
add the job to any other pipeline type.
```yaml ```yaml
job: job:
...@@ -1239,11 +1247,8 @@ job: ...@@ -1239,11 +1247,8 @@ job:
- if: '$CI_PIPELINE_SOURCE == "push"' - if: '$CI_PIPELINE_SOURCE == "push"'
``` ```
This example runs the job as a manual job in scheduled pipelines or in push The following example runs the job as a `when: on_success` job in [merge request pipelines](../merge_request_pipelines/index.md)
pipelines (to branches or tags), with `when: on_success` (default). It does not and scheduled pipelines. It does not run in any other pipeline type.
add the job to any other pipeline type.
Another example:
```yaml ```yaml
job: job:
...@@ -1253,9 +1258,6 @@ job: ...@@ -1253,9 +1258,6 @@ job:
- if: '$CI_PIPELINE_SOURCE == "schedule"' - if: '$CI_PIPELINE_SOURCE == "schedule"'
``` ```
This example runs the job as a `when: on_success` job in [merge request pipelines](../merge_request_pipelines/index.md)
and scheduled pipelines. It does not run in any other pipeline type.
Other commonly used variables for `if` clauses: Other commonly used variables for `if` clauses:
- `if: $CI_COMMIT_TAG`: If changes are pushed for a tag. - `if: $CI_COMMIT_TAG`: If changes are pushed for a tag.
...@@ -1272,11 +1274,11 @@ Other commonly used variables for `if` clauses: ...@@ -1272,11 +1274,11 @@ Other commonly used variables for `if` clauses:
#### `rules:changes` #### `rules:changes`
`rules:changes` determines whether or not to add jobs to a pipeline by checking for Use `rules:changes` to specify when to add a job to a pipeline by checking for
changes to specific files. changes to specific files.
`rules: changes` works exactly the same way as [`only: changes` and `except: changes`](#onlychangesexceptchanges), `rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychangesexceptchanges).
accepting an array of paths. It's recommended to only use `rules: changes` with branch It accepts an array of paths. You should use `rules: changes` only with branch
pipelines or merge request pipelines. For example, it's common to use `rules: changes` pipelines or merge request pipelines. For example, it's common to use `rules: changes`
with merge request pipelines: with merge request pipelines:
...@@ -1299,7 +1301,7 @@ In this example: ...@@ -1299,7 +1301,7 @@ In this example:
- If `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`). - If `Dockerfile` has not changed, do not add job to any pipeline (same as `when: never`).
To use `rules: changes` with branch pipelines instead of merge request pipelines, To use `rules: changes` with branch pipelines instead of merge request pipelines,
change the `if:` clause in the example above to: change the `if:` clause in the previous example to:
```yaml ```yaml
rules: rules:
...@@ -1321,7 +1323,7 @@ if there is no `if:` statement that limits the job to branch or merge request pi ...@@ -1321,7 +1323,7 @@ if there is no `if:` statement that limits the job to branch or merge request pi
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34272) in GitLab 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34272) in GitLab 13.6.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267192) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267192) in GitLab 13.7.
CI/CD variables can be used in `rules:changes` expressions to determine when You can use CI/CD variables in `rules:changes` expressions to determine when
to add jobs to a pipeline: to add jobs to a pipeline:
```yaml ```yaml
...@@ -1334,7 +1336,7 @@ docker build: ...@@ -1334,7 +1336,7 @@ docker build:
- $DOCKERFILES_DIR/* - $DOCKERFILES_DIR/*
``` ```
You can use The `$` character for both variables and paths. For example, if the You can use the `$` character for both variables and paths. For example, if the
`$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the
`$` is interpreted as being part of a path. `$` is interpreted as being part of a path.
...@@ -1342,10 +1344,10 @@ You can use The `$` character for both variables and paths. For example, if the ...@@ -1342,10 +1344,10 @@ You can use The `$` character for both variables and paths. For example, if the
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4.
`exists` accepts an array of paths and matches if any of these paths exist Use `exists` to run a job when certain files exist in the repository.
as files in the repository. You can use an array of paths.
In this example, `job` runs if a `Dockerfile` exists anywhere in the repository: In the following example, `job` runs if a `Dockerfile` exists anywhere in the repository:
```yaml ```yaml
job: job:
...@@ -1378,11 +1380,11 @@ For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns. A ...@@ -1378,11 +1380,11 @@ For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns. A
You can use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail, or a manual job to You can use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail, or a manual job to
wait for action, without stopping the pipeline itself. All jobs that use `rules:` default to `allow_failure: false` wait for action, without stopping the pipeline itself. All jobs that use `rules:` default to `allow_failure: false`
if `allow_failure:` is not defined. if you do not define `allow_failure:`.
The rule-level `rules:allow_failure` option overrides the job-level The rule-level `rules:allow_failure` option overrides the job-level
[`allow_failure`](#allow_failure) option, and is only applied when the job is [`allow_failure`](#allow_failure) option, and is only applied when
triggered by the particular rule. the particular rule triggers the job.
```yaml ```yaml
job: job:
...@@ -1400,7 +1402,7 @@ In this example, if the first rule matches, then the job has `when: manual` and ...@@ -1400,7 +1402,7 @@ In this example, if the first rule matches, then the job has `when: manual` and
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209864) in GitLab 13.7. > - [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. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289803) in GitLab 13.10.
You can use [`variables`](#variables) in `rules:` to define variables for specific conditions. Use [`variables`](#variables) in `rules:` to define variables for specific conditions.
For example: For example:
...@@ -1476,14 +1478,14 @@ to add jobs to pipelines, use [`rules`](#rules). ...@@ -1476,14 +1478,14 @@ to add jobs to pipelines, use [`rules`](#rules).
1. `except` defines the names of branches and tags the job does 1. `except` defines the names of branches and tags the job does
**not** run for. **not** run for.
There are a few rules that apply to the usage of job policy: A few rules apply to the usage of job policy:
- `only` and `except` are inclusive. If both `only` and `except` are defined - `only` and `except` are inclusive. If both `only` and `except` are defined
in a job specification, the ref is filtered by `only` and `except`. in a job specification, the ref is filtered by `only` and `except`.
- `only` and `except` can use regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)). - `only` and `except` can use regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)).
- `only` and `except` can specify a repository path to filter jobs for forks. - `only` and `except` can specify a repository path to filter jobs for forks.
In addition, `only` and `except` can use special keywords: In addition, `only` and `except` can use these keywords:
| **Value** | **Description** | | **Value** | **Description** |
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
...@@ -1504,8 +1506,8 @@ Scheduled pipelines run on specific branches, so jobs configured with `only: bra ...@@ -1504,8 +1506,8 @@ Scheduled pipelines run on specific branches, so jobs configured with `only: bra
run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches` run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches`
from running on scheduled pipelines. from running on scheduled pipelines.
In the example below, `job` runs only for refs that start with `issue-`, In the following example, `job` runs only for refs that start with `issue-`.
whereas all branches are skipped: All branches are skipped:
```yaml ```yaml
job: job:
...@@ -1517,8 +1519,8 @@ job: ...@@ -1517,8 +1519,8 @@ job:
- branches - branches
``` ```
Pattern matching is case-sensitive by default. Use `i` flag modifier, like Pattern matching is case-sensitive by default. Use the `i` flag modifier, like
`/pattern/i` to make a pattern case-insensitive: `/pattern/i`, to make a pattern case-insensitive:
```yaml ```yaml
job: job:
...@@ -1530,8 +1532,8 @@ job: ...@@ -1530,8 +1532,8 @@ job:
- branches - branches
``` ```
In this example, `job` runs only for refs that are tagged, or if a build is In the following example, `job` runs only for refs that are tagged, or if a build is
explicitly requested by an API trigger or a [Pipeline Schedule](../pipelines/schedules.md): explicitly requested by an API trigger or a [pipeline schedule](../pipelines/schedules.md):
```yaml ```yaml
job: job:
...@@ -1542,8 +1544,7 @@ job: ...@@ -1542,8 +1544,7 @@ job:
- schedules - schedules
``` ```
Use the repository path to have jobs executed only for the parent To execute jobs only for the parent repository and not forks:
repository and not forks:
```yaml ```yaml
job: job:
...@@ -1554,11 +1555,11 @@ job: ...@@ -1554,11 +1555,11 @@ job:
- /^release/.*$/@gitlab-org/gitlab - /^release/.*$/@gitlab-org/gitlab
``` ```
The above example runs `job` for all branches on `gitlab-org/gitlab`, This example runs `job` for all branches on `gitlab-org/gitlab`,
except `master` and those with names prefixed with `release/`. except `master` and branches that start with `release/`.
If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by
default. If it does not have an `except` rule, it's empty. default. If the job does not have an `except` rule, it's empty.
For example, `job1` and `job2` are essentially the same: For example, `job1` and `job2` are essentially the same:
...@@ -1634,7 +1635,7 @@ the pipeline if the following is true: ...@@ -1634,7 +1635,7 @@ the pipeline if the following is true:
- `(any listed refs are true) AND (any listed variables are true) AND (any listed changes are true) AND (any chosen Kubernetes status matches)` - `(any listed refs are true) AND (any listed variables are true) AND (any listed changes are true) AND (any chosen Kubernetes status matches)`
In the example below, the `test` job is `only` created when **all** of the following are true: In the following example, the `test` job is `only` created when **all** of the following are true:
- The pipeline is [scheduled](../pipelines/schedules.md) **or** runs for `master`. - The pipeline is [scheduled](../pipelines/schedules.md) **or** runs for `master`.
- The `variables` keyword matches. - The `variables` keyword matches.
...@@ -1657,7 +1658,7 @@ added if the following is true: ...@@ -1657,7 +1658,7 @@ added if the following is true:
- `(any listed refs are true) OR (any listed variables are true) OR (any listed changes are true) OR (a chosen Kubernetes status matches)` - `(any listed refs are true) OR (any listed variables are true) OR (any listed changes are true) OR (a chosen Kubernetes status matches)`
In the example below, the `test` job is **not** created when **any** of the following are true: In the following example, the `test` job is **not** created when **any** of the following are true:
- The pipeline runs for the `master` branch. - The pipeline runs for the `master` branch.
- There are changes to the `README.md` file in the root directory of the repository. - There are changes to the `README.md` file in the root directory of the repository.
...@@ -1679,7 +1680,7 @@ test: ...@@ -1679,7 +1680,7 @@ test:
The `refs` strategy can take the same values as the The `refs` strategy can take the same values as the
[simplified only/except configuration](#onlyexcept-basic). [simplified only/except configuration](#onlyexcept-basic).
In the example below, the `deploy` job is created only when the In the following example, the `deploy` job is created only when the
pipeline is [scheduled](../pipelines/schedules.md) or runs for the `master` branch: pipeline is [scheduled](../pipelines/schedules.md) or runs for the `master` branch:
```yaml ```yaml
...@@ -1696,7 +1697,7 @@ deploy: ...@@ -1696,7 +1697,7 @@ deploy:
The `kubernetes` strategy accepts only the `active` keyword. The `kubernetes` strategy accepts only the `active` keyword.
In the example below, the `deploy` job is created only when the In the following example, the `deploy` job is created only when the
Kubernetes service is active in the project: Kubernetes service is active in the project:
```yaml ```yaml
...@@ -1767,7 +1768,7 @@ In pipelines with [sources other than the three above](../variables/predefined_v ...@@ -1767,7 +1768,7 @@ In pipelines with [sources other than the three above](../variables/predefined_v
You can configure jobs to use `only: changes` with other `only: refs` keywords. However, You can configure jobs to use `only: changes` with other `only: refs` keywords. However,
those jobs ignore the changes and always run. those jobs ignore the changes and always run.
In this example, when you push commits to an existing branch, the `docker build` job In the following example, when you push commits to an existing branch, the `docker build` job
runs only if any of these files change: runs only if any of these files change:
- The `Dockerfile` file. - The `Dockerfile` file.
...@@ -1864,7 +1865,7 @@ docker build service one: ...@@ -1864,7 +1865,7 @@ docker build service one:
- service-one/**/* - service-one/**/*
``` ```
In the example above, the pipeline might fail because of changes to a file in `service-one/**/*`. In this example, the pipeline might fail because of changes to a file in `service-one/**/*`.
A later commit that doesn't have changes in `service-one/**/*` A later commit that doesn't have changes in `service-one/**/*`
but does have changes to the `Dockerfile` can pass. The job but does have changes to the `Dockerfile` can pass. The job
...@@ -1898,13 +1899,22 @@ All files are considered to have changed when a scheduled pipeline runs. ...@@ -1898,13 +1899,22 @@ All files are considered to have changed when a scheduled pipeline runs.
> - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50. > - 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/30631) in GitLab 12.8, `needs: []` lets jobs start immediately.
Use the `needs:` keyword to execute jobs out-of-order. Relationships between jobs 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). that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md).
You can ignore stage ordering and run some jobs without waiting for others to complete. You can ignore stage ordering and run some jobs without waiting for others to complete.
Jobs in multiple stages can run concurrently. Jobs in multiple stages can run concurrently.
Let's consider the following example: The following example creates four paths of execution:
- Linter: the `lint` job runs immediately without waiting for the `build` stage
to complete because it has no needs (`needs: []`).
- Linux path: the `linux:rspec` and `linux:rubocop` jobs runs as soon as the `linux:build`
job finishes without waiting for `mac:build` to finish.
- macOS path: the `mac:rspec` and `mac:rubocop` 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; in this case:
`linux:build`, `linux:rspec`, `linux:rubocop`, `mac:build`, `mac:rspec`, `mac:rubocop`.
```yaml ```yaml
linux:build: linux:build:
...@@ -1937,20 +1947,6 @@ production: ...@@ -1937,20 +1947,6 @@ production:
stage: deploy stage: deploy
``` ```
This example creates four paths of execution:
- Linter: the `lint` job runs immediately without waiting for the `build` stage to complete because it has no needs (`needs: []`).
- Linux path: the `linux:rspec` and `linux:rubocop` jobs runs as soon
as the `linux:build` job finishes without waiting for `mac:build` to finish.
- macOS path: the `mac:rspec` and `mac:rubocop` 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; in this case: `linux:build`, `linux:rspec`, `linux:rubocop`,
`mac:build`, `mac:rspec`, `mac:rubocop`.
#### Requirements and limitations #### Requirements and limitations
- If `needs:` is set to point to a job that is not instantiated - If `needs:` is set to point to a job that is not instantiated
...@@ -1967,7 +1963,7 @@ This example creates four paths of execution: ...@@ -1967,7 +1963,7 @@ This example creates four paths of execution:
- `needs:` is similar to `dependencies:` in that it must use jobs from prior stages, - `needs:` is similar to `dependencies:` in that it must use jobs from prior stages,
meaning it's impossible to create circular dependencies. Depending on jobs in the meaning it's impossible to create circular dependencies. Depending on jobs in the
current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/30632). current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/30632).
- Related to the above, stages must be explicitly defined for all jobs - Stages must be explicitly defined for all jobs
that have the keyword `needs:` or are referred to by one. that have the keyword `needs:` or are referred to by one.
##### Changing the `needs:` job limit **(FREE SELF)** ##### Changing the `needs:` job limit **(FREE SELF)**
...@@ -1990,7 +1986,7 @@ To disable directed acyclic graphs (DAG), set the limit to `0`. ...@@ -1990,7 +1986,7 @@ To disable directed acyclic graphs (DAG), set the limit to `0`.
Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are
downloaded in jobs that use `needs`. downloaded in jobs that use `needs`.
In this example, the `rspec` job downloads the `build_job` artifacts, but the In the following example, the `rspec` job downloads the `build_job` artifacts, but the
`rubocop` job does not: `rubocop` job does not:
```yaml ```yaml
...@@ -2013,7 +2009,7 @@ rubocop: ...@@ -2013,7 +2009,7 @@ rubocop:
artifacts: false artifacts: false
``` ```
In this example, the `rspec` job downloads the artifacts from all three `build_jobs`. In the following example, the `rspec` job downloads the artifacts from all three `build_jobs`.
`artifacts` is: `artifacts` is:
- Set to true for `build_job_1`. - Set to true for `build_job_1`.
...@@ -2064,7 +2060,7 @@ The user running the pipeline must have at least `reporter` access to the group ...@@ -2064,7 +2060,7 @@ The user running the pipeline must have at least `reporter` access to the group
Use `needs` to download artifacts from different pipelines in the current project. Use `needs` to download artifacts from different pipelines in the current project.
Set the `project` keyword as the current project's name, and specify a ref. Set the `project` keyword as the current project's name, and specify a ref.
In this example, `build_job` downloads the artifacts for the latest successful In the following example, `build_job` downloads the artifacts for the latest successful
`build-1` job with the `other-ref` ref: `build-1` job with the `other-ref` ref:
```yaml ```yaml
...@@ -2153,7 +2149,7 @@ available for the project. ...@@ -2153,7 +2149,7 @@ available for the project.
When you register a runner, you can specify the runner's tags, for When you register a runner, you can specify the runner's tags, for
example `ruby`, `postgres`, `development`. example `ruby`, `postgres`, `development`.
In this example, the job is run by a runner that In the following example, the job is run by a runner that
has both `ruby` and `postgres` tags defined. has both `ruby` and `postgres` tags defined.
```yaml ```yaml
...@@ -2202,7 +2198,7 @@ Assuming all other jobs are successful, the job's stage and its pipeline ...@@ -2202,7 +2198,7 @@ Assuming all other jobs are successful, the job's stage and its pipeline
show the same orange warning. However, the associated commit is marked as show the same orange warning. However, the associated commit is marked as
"passed", without warnings. "passed", without warnings.
In the example below, `job1` and `job2` run in parallel, but if `job1` In the following example, `job1` and `job2` run in parallel. If `job1`
fails, it doesn't stop the next stage from running, because it's marked with fails, it doesn't stop the next stage from running, because it's marked with
`allow_failure: true`: `allow_failure: true`:
...@@ -2269,7 +2265,12 @@ The valid values of `when` are: ...@@ -2269,7 +2265,12 @@ The valid values of `when` are:
- With [`rules`](#rules), don't execute job. - With [`rules`](#rules), don't execute job.
- With [`workflow`](#workflow), don't run pipeline. - With [`workflow`](#workflow), don't run pipeline.
For example: In the following 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.
```yaml ```yaml
stages: stages:
...@@ -2308,13 +2309,6 @@ cleanup_job: ...@@ -2308,13 +2309,6 @@ cleanup_job:
when: always when: always
``` ```
The above 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.
#### `when:manual` #### `when:manual`
A manual job is a type of job that is not executed automatically and must be explicitly A manual job is a type of job that is not executed automatically and must be explicitly
...@@ -2377,7 +2371,7 @@ To protect a manual job: ...@@ -2377,7 +2371,7 @@ To protect a manual job:
``` ```
1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments), 1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments),
select the environment (`production` in the example above) and add the users, roles or groups select the environment (`production` in this example) and add the users, roles or groups
that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in
this list can trigger this manual job, as well as GitLab administrators this list can trigger this manual job, as well as GitLab administrators
who are always able to use protected environments. who are always able to use protected environments.
...@@ -2670,7 +2664,7 @@ as Review Apps. You can see an example that uses Review Apps at ...@@ -2670,7 +2664,7 @@ as Review Apps. You can see an example that uses Review Apps at
### `cache` ### `cache`
Use the `cache` keyword to specify a list of files and directories to 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. cache between jobs. You can only use paths that are in the local working copy.
If `cache` is defined outside the scope of jobs, it's set If `cache` is defined outside the scope of jobs, it's set
...@@ -2771,7 +2765,7 @@ to download cache that's tagged with `test`. ...@@ -2771,7 +2765,7 @@ to download cache that's tagged with `test`.
If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to
specify a cache to use when none exists. specify a cache to use when none exists.
In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined In the following example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined
by the `CACHE_FALLBACK_KEY` variable: by the `CACHE_FALLBACK_KEY` variable:
```yaml ```yaml
...@@ -2808,7 +2802,7 @@ cache: ...@@ -2808,7 +2802,7 @@ cache:
- node_modules - node_modules
``` ```
In this example we're creating a cache for Ruby and Node.js dependencies that This example creates a cache for Ruby and Node.js dependencies that
is tied to current versions of the `Gemfile.lock` and `package.json` files. Whenever one of is tied to current versions of the `Gemfile.lock` and `package.json` files. Whenever one of
these files changes, a new cache key is computed and a new cache is created. Any future 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` job runs that use the same `Gemfile.lock` and `package.json` with `cache:key:files`
...@@ -2942,7 +2936,7 @@ To do so, add `policy: push` to the job. ...@@ -2942,7 +2936,7 @@ To do so, add `policy: push` to the job.
### `artifacts` ### `artifacts`
Use the `artifacts` keyword to specify a list of files and directories that are Use `artifacts` to specify a list of files and directories that are
attached to the job when it [succeeds, fails, or always](#artifactswhen). attached to the job when it [succeeds, fails, or always](#artifactswhen).
The artifacts are sent to GitLab after the job finishes. They are The artifacts are sent to GitLab after the job finishes. They are
...@@ -3422,7 +3416,7 @@ If `retry` is set to `2`, and a job succeeds in a second run (first retry), it i ...@@ -3422,7 +3416,7 @@ If `retry` is set to `2`, and a job succeeds in a second run (first retry), it i
The `retry` value must be a positive integer, from `0` to `2` The `retry` value must be a positive integer, from `0` to `2`
(two retries maximum, three runs in total). (two retries maximum, three runs in total).
This example retries all failure cases: The following example retries all failure cases:
```yaml ```yaml
test: test:
...@@ -3584,7 +3578,7 @@ deploystacks: ...@@ -3584,7 +3578,7 @@ deploystacks:
STACK: [data, processing] STACK: [data, processing]
``` ```
This example generates 10 parallel `deploystacks` jobs, each with different values The following example generates 10 parallel `deploystacks` jobs, each with different values
for `PROVIDER` and `STACK`: for `PROVIDER` and `STACK`:
```plaintext ```plaintext
...@@ -3769,6 +3763,10 @@ To force the `trigger` job to wait for the downstream (multi-project or child) p ...@@ -3769,6 +3763,10 @@ To force the `trigger` job to wait for the downstream (multi-project or child) p
pipeline completes. At that point, the `trigger` job completes and displays the same status as pipeline completes. At that point, the `trigger` job completes and displays the same status as
the downstream job. the downstream job.
This setting can help keep your pipeline execution linear. In the following example, jobs from
subsequent stages wait for the triggered pipeline to successfully complete before
starting, which reduces parallelization.
```yaml ```yaml
trigger_job: trigger_job:
trigger: trigger:
...@@ -3776,10 +3774,6 @@ trigger_job: ...@@ -3776,10 +3774,6 @@ trigger_job:
strategy: depend strategy: depend
``` ```
This setting can help keep your pipeline execution linear. In the example above, jobs from
subsequent stages wait for the triggered pipeline to successfully complete before
starting, which reduces parallelization.
#### Trigger a pipeline by API call #### Trigger a pipeline by API call
To force a rebuild of a specific branch, tag, or commit, you can use an API call To force a rebuild of a specific branch, tag, or commit, you can use an API call
...@@ -3806,7 +3800,12 @@ When enabled, a pipeline is immediately canceled when a new pipeline starts on t ...@@ -3806,7 +3800,12 @@ When enabled, a pipeline is immediately canceled when a new pipeline starts on t
Set jobs as interruptible that can be safely canceled once started (for instance, a build job). Set jobs as interruptible that can be safely canceled once started (for instance, a build job).
For example: In the following example, a new pipeline run causes an existing running pipeline to be:
- Canceled, if only `step-1` is running or pending.
- Not canceled, once `step-2` starts running.
After an uninterruptible job starts running, the pipeline cannot be canceled.
```yaml ```yaml
stages: stages:
...@@ -3832,13 +3831,6 @@ step-3: ...@@ -3832,13 +3831,6 @@ step-3:
interruptible: true interruptible: true
``` ```
In the example above, a new pipeline run causes an existing running pipeline to be:
- Canceled, if only `step-1` is running or pending.
- Not canceled, once `step-2` starts running.
When an uninterruptible job is running, the pipeline cannot be canceled, regardless of the final job's state.
### `resource_group` ### `resource_group`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7.
...@@ -3885,7 +3877,7 @@ executions. The [`trigger` keyword](#trigger) can trigger downstream pipelines. ...@@ -3885,7 +3877,7 @@ executions. The [`trigger` keyword](#trigger) can trigger downstream pipelines.
[`resource_group` keyword](#resource_group) can co-exist with it. This is useful to control the [`resource_group` keyword](#resource_group) can co-exist with it. This is useful to control the
concurrency for deployment pipelines, while running non-sensitive jobs concurrently. concurrency for deployment pipelines, while running non-sensitive jobs concurrently.
This example has two pipeline configurations in a project. When a pipeline starts running, The following example has two pipeline configurations in a project. When a pipeline starts running,
non-sensitive jobs are executed first and aren't affected by concurrent executions in other non-sensitive jobs are executed first and aren't affected by concurrent executions in other
pipelines. However, GitLab ensures that there are no other deployment pipelines running before pipelines. However, GitLab ensures that there are no other deployment pipelines running before
triggering a deployment (child) pipeline. If other deployment pipelines are running, GitLab waits triggering a deployment (child) pipeline. If other deployment pipelines are running, GitLab waits
...@@ -3926,7 +3918,7 @@ deployment: ...@@ -3926,7 +3918,7 @@ deployment:
script: echo "Deploying..." script: echo "Deploying..."
``` ```
Note that you must define [`strategy: depend`](#linking-pipelines-with-triggerstrategy) You must define [`strategy: depend`](#linking-pipelines-with-triggerstrategy)
with the `trigger` keyword. This ensures that the lock isn't released until the downstream pipeline with the `trigger` keyword. This ensures that the lock isn't released until the downstream pipeline
finishes. finishes.
...@@ -3934,7 +3926,7 @@ finishes. ...@@ -3934,7 +3926,7 @@ finishes.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) in GitLab 13.2. > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) in GitLab 13.2.
`release` indicates that the job creates a [Release](../../user/project/releases/index.md). Use `release` to create a [release](../../user/project/releases/index.md).
These keywords are supported: These keywords are supported:
...@@ -3945,18 +3937,18 @@ These keywords are supported: ...@@ -3945,18 +3937,18 @@ These keywords are supported:
- [`milestones`](#releasemilestones) (optional) - [`milestones`](#releasemilestones) (optional)
- [`released_at`](#releasereleased_at) (optional) - [`released_at`](#releasereleased_at) (optional)
The Release is created only if the job processes without error. If the Rails API The release is created only if the job processes without error. If the Rails API
returns an error during Release creation, the `release` job fails. returns an error during release creation, the `release` job fails.
#### `release-cli` Docker image #### `release-cli` Docker image
The Docker image to use for the `release-cli` must be specified, using the following directive: You must specify the Docker image to use for the `release-cli`:
```yaml ```yaml
image: registry.gitlab.com/gitlab-org/release-cli:latest image: registry.gitlab.com/gitlab-org/release-cli:latest
``` ```
#### Script #### `script`
All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release` All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release`
job can use the output from script commands, but you can use a placeholder script if job can use the output from script commands, but you can use a placeholder script if
...@@ -3989,11 +3981,12 @@ android-release: ...@@ -3989,11 +3981,12 @@ android-release:
#### `release:tag_name` #### `release:tag_name`
The `tag_name` must be specified. It can refer to an existing Git tag or can be specified by the user. You must specify a `tag_name` for the release. The tag can refer to an existing Git tag or
you can specify a new tag.
When the specified tag doesn't exist in the repository, a new tag is created from the associated SHA of the pipeline. When the specified tag doesn't exist in the repository, a new tag is created from the associated SHA of the pipeline.
For example, when creating a Release from a Git tag: For example, when creating a release from a Git tag:
```yaml ```yaml
job: job:
...@@ -4012,17 +4005,17 @@ job: ...@@ -4012,17 +4005,17 @@ job:
description: 'Release description' description: 'Release description'
``` ```
- The Release is created only if the job's main script succeeds. - The release is created only if the job's main script succeeds.
- If the Release already exists, it is not updated and the job with the `release` keyword fails. - If the release already exists, it is not updated and the job with the `release` keyword fails.
- The `release` section executes after the `script` tag and before the `after_script`. - The `release` section executes after the `script` tag and before the `after_script`.
#### `release:name` #### `release:name`
The Release name. If omitted, it is populated with the value of `release: tag_name`. The release name. If omitted, it is populated with the value of `release: tag_name`.
#### `release:description` #### `release:description`
Specifies the long description of the Release. You can also specify a file that contains the Specifies the long description of the release. You can also specify a file that contains the
description. description.
##### Read description from a file ##### Read description from a file
...@@ -4060,8 +4053,7 @@ released_at: '2021-03-15T08:00:00Z' ...@@ -4060,8 +4053,7 @@ released_at: '2021-03-15T08:00:00Z'
#### Complete example for `release` #### Complete example for `release`
Combining the individual examples given above for `release` results in the following If you combine the previous examples for `release`, you get two options, depending on how you generate the
code snippets. There are two options, depending on how you generate the
tags. You can't use these options together, so choose one: tags. You can't use these options together, so choose one:
- To create a release when you push a Git tag, or when you add a Git tag - To create a release when you push a Git tag, or when you add a Git tag
...@@ -4145,7 +4137,7 @@ The entries under the `release` node are transformed into a `bash` command line ...@@ -4145,7 +4137,7 @@ The entries under the `release` node are transformed into a `bash` command line
to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli). to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli).
You can also call the `release-cli` directly from a `script` entry. You can also call the `release-cli` directly from a `script` entry.
For example, using the YAML described above: For example, if you use the YAML described previously:
```shell ```shell
release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3"
...@@ -4155,7 +4147,7 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using ...@@ -4155,7 +4147,7 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) in GitLab 13.4. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) in GitLab 13.4.
`secrets` indicates the [CI/CD Secrets](../secrets/index.md) this job needs. It should be a hash, Use `secrets` to specify the [CI/CD Secrets](../secrets/index.md) the job needs. It should be a hash,
and the keys should be the names of the variables that are made available to the job. and the keys should be the names of the variables that are made available to the job.
The value of each secret is saved in a temporary file. This file's path is stored in these The value of each secret is saved in a temporary file. This file's path is stored in these
variables. variables.
...@@ -4164,7 +4156,8 @@ variables. ...@@ -4164,7 +4156,8 @@ variables.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4.
`vault` keyword specifies secrets provided by [Hashicorp's Vault](https://www.vaultproject.io/). Use `vault` to specify secrets provided by [Hashicorp's Vault](https://www.vaultproject.io/).
This syntax has multiple forms. The shortest form assumes the use of the This syntax has multiple forms. The shortest form assumes the use of the
[KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) secrets engine, [KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) secrets engine,
mounted at the default path `kv-v2`. The last part of the secret's path is the mounted at the default path `kv-v2`. The last part of the secret's path is the
...@@ -4202,14 +4195,13 @@ job: ...@@ -4202,14 +4195,13 @@ job:
### `pages` ### `pages`
`pages` is a special job that uploads static content to GitLab that Use `pages` to upload static content to GitLab. The content
is then published as a website. It has a special syntax, so the two is then published as a website. You must:
requirements below must be met:
- Any static content must be placed under a `public/` directory. - Place any static content in a `public/` directory.
- `artifacts` with a path to the `public/` directory must be defined. - Define [`artifacts`](#artifacts) with a path to the `public/` directory.
The example below moves all files from the root of the project to the The following 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/` directory. The `.public` workaround is so `cp` does not also copy
`public/` to itself in an infinite loop: `public/` to itself in an infinite loop:
...@@ -4227,14 +4219,14 @@ pages: ...@@ -4227,14 +4219,14 @@ pages:
- master - master
``` ```
Read more on [GitLab Pages user documentation](../../user/project/pages/index.md). View the [GitLab Pages user documentation](../../user/project/pages/index.md).
### `inherit` ### `inherit`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9.
You can disable inheritance of globally defined defaults Use `inherit:` to control inheritance of globally-defined defaults
and variables with the `inherit:` keyword. and variables.
To enable or disable the inheritance of all `default:` or `variables:` keywords, use: To enable or disable the inheritance of all `default:` or `variables:` keywords, use:
...@@ -4263,7 +4255,7 @@ inherit: ...@@ -4263,7 +4255,7 @@ inherit:
- VARIABLE2 - VARIABLE2
``` ```
In the example below: In the following example:
- `rubocop`: - `rubocop`:
- inherits: Nothing. - inherits: Nothing.
...@@ -4367,7 +4359,7 @@ You can use [YAML anchors for variables](#yaml-anchors-for-variables). ...@@ -4367,7 +4359,7 @@ You can use [YAML anchors for variables](#yaml-anchors-for-variables).
> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7. > [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7.
You can use the `value` and `description` keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) Use the `value` and `description` keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines)
when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually): when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually):
```yaml ```yaml
...@@ -4379,7 +4371,7 @@ variables: ...@@ -4379,7 +4371,7 @@ variables:
### Configure runner behavior with variables ### Configure runner behavior with variables
You can use [CI/CD variables](../variables/README.md) to configure runner Git behavior: You can use [CI/CD variables](../variables/README.md) to configure how the runner processes Git requests:
- [`GIT_STRATEGY`](../runners/README.md#git-strategy) - [`GIT_STRATEGY`](../runners/README.md#git-strategy)
- [`GIT_SUBMODULE_STRATEGY`](../runners/README.md#git-submodule-strategy) - [`GIT_SUBMODULE_STRATEGY`](../runners/README.md#git-submodule-strategy)
...@@ -4395,16 +4387,16 @@ You can use [CI/CD variables](../variables/README.md) to configure runner Git be ...@@ -4395,16 +4387,16 @@ You can use [CI/CD variables](../variables/README.md) to configure runner Git be
You can also use variables to configure how many times a runner You can also use variables to configure how many times a runner
[attempts certain stages of job execution](../runners/README.md#job-stages-attempts). [attempts certain stages of job execution](../runners/README.md#job-stages-attempts).
## Special YAML features ## YAML-specific features
It's possible to use special YAML features like anchors (`&`), aliases (`*`) In your `.gitlab-ci.yml` file, you can use YAML-specific features like anchors (`&`), aliases (`*`),
and map merging (`<<`). Use these features to reduce the complexity and map merging (`<<`). Use these features to reduce the complexity
of the code in the `.gitlab-ci.yml` file. of the code in the `.gitlab-ci.yml` file.
Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/). Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/).
In most cases, the [`extends` keyword](#extends) is more user friendly and should In most cases, the [`extends` keyword](#extends) is more user friendly and you should
be used over these special YAML features. use it when possible.
You can use YAML anchors to merge YAML arrays. You can use YAML anchors to merge YAML arrays.
...@@ -4445,8 +4437,8 @@ test2: ...@@ -4445,8 +4437,8 @@ test2:
``` ```
`&` sets up the name of the anchor (`job_configuration`), `<<` means "merge the `&` sets up the name of the anchor (`job_configuration`), `<<` means "merge the
given hash into the current one", and `*` includes the named anchor given hash into the current one," and `*` includes the named anchor
(`job_configuration` again). The expanded version of the example above is: (`job_configuration` again). The expanded version of this example is:
```yaml ```yaml
.job_template: .job_template:
...@@ -4586,7 +4578,7 @@ Use [YAML anchors](#anchors) with `variables` to repeat assignment ...@@ -4586,7 +4578,7 @@ Use [YAML anchors](#anchors) with `variables` to repeat assignment
of variables across multiple jobs. You can also use YAML anchors when a job of variables across multiple jobs. You can also use YAML anchors when a job
requires a specific `variables` block that would otherwise override the global variables. requires a specific `variables` block that would otherwise override the global variables.
In the example below, we override the `GIT_STRATEGY` variable without affecting The following example shows how override the `GIT_STRATEGY` variable without affecting
the use of the `SAMPLE_VARIABLE` variable: the use of the `SAMPLE_VARIABLE` variable:
```yaml ```yaml
...@@ -4606,7 +4598,7 @@ job_no_git_strategy: ...@@ -4606,7 +4598,7 @@ job_no_git_strategy:
### Hide jobs ### Hide jobs
If you want to temporarily 'disable' a job, rather than commenting out all the If you want to temporarily disable a job, rather than commenting out all the
lines where the job is defined: lines where the job is defined:
```yaml ```yaml
...@@ -4625,7 +4617,7 @@ GitLab CI/CD. In the following example, `.hidden_job` is ignored: ...@@ -4625,7 +4617,7 @@ GitLab CI/CD. In the following example, `.hidden_job` is ignored:
``` ```
Use this feature to ignore jobs, or use the Use this feature to ignore jobs, or use the
[special YAML features](#special-yaml-features) and transform the hidden jobs [YAML-specific features](#yaml-specific-features) and transform the hidden jobs
into templates. into templates.
### `!reference` tags ### `!reference` tags
...@@ -4637,7 +4629,7 @@ sections and reuse it in the current section. Unlike [YAML anchors](#anchors), y ...@@ -4637,7 +4629,7 @@ sections and reuse it in the current section. Unlike [YAML anchors](#anchors), y
use `!reference` tags to reuse configuration from [included](#include) configuration use `!reference` tags to reuse configuration from [included](#include) configuration
files as well. files as well.
In this example, a `script` and an `after_script` from two different locations are In the following example, a `script` and an `after_script` from two different locations are
reused in the `test` job: reused in the `test` job:
- `setup.yml`: - `setup.yml`:
...@@ -4666,7 +4658,7 @@ reused in the `test` job: ...@@ -4666,7 +4658,7 @@ reused in the `test` job:
- !reference [.teardown, after_script] - !reference [.teardown, after_script]
``` ```
In this example, `test-vars-1` reuses the all the variables in `.vars`, while `test-vars-2` In the following example, `test-vars-1` reuses the all the variables in `.vars`, while `test-vars-2`
selects a specific variable and reuses it as a new `MY_VAR` variable. selects a specific variable and reuses it as a new `MY_VAR` variable.
```yaml ```yaml
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7