Skip to content

G
gitlab-ce
Commit b6eaef6f authored by Marcel Amirault's avatar Marcel Amirault
Browse files
Options

Merge branch 'selhorn-ci-yaml-123' into 'master' 

Edited for style and consistency

See merge request gitlab-org/gitlab!55677
parents 26b813ce 4fa9ffec
Show whitespace changes
Inline Side-by-side
Showing with 218 additions and 226 deletions
doc/ci/yaml/README.md
View file @ b6eaef6f
......@@ -46,7 +46,7 @@ The keywords available for jobs are:
| [`only`](#onlyexcept-basic) | Limit when jobs are created. |
| [`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. |
| [`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. |
| [`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. |
......@@ -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
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)
- [`artifacts`](#artifacts)
......@@ -92,7 +92,7 @@ The following job keywords can be defined inside a `default:` section:
- [`tags`](#tags)
- [`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
a job-specific `image:` section:
......@@ -159,9 +159,9 @@ the [`needs`](#needs) keyword.
> [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.
It accepts a single `rules:` keyword that is similar to [`rules:` defined in jobs](#rules).
Use it to define what can trigger a new pipeline.
Use `workflow:` to determine whether or not a pipeline is created.
Define this keyword at the top level, with a single `rules:` keyword that
is similar to [`rules:` defined in jobs](#rules).
You can use the [`workflow:rules` templates](#workflowrules-templates) to import
a preconfigured `workflow: rules` entry.
......@@ -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.
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
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:
......@@ -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.
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.
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.
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
[Merge Request Pipelines](../merge_request_pipelines/), like
[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results)
or [Merge Trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/).
Use this template if you are intentionally avoiding those features.
[merge request pipelines](../merge_request_pipelines/), like
[pipelines for merge results](../merge_request_pipelines/#pipelines-for-merged-results)
or [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/).
This template intentionally avoids those features.
It is [included](#include) as follows:
To [include](#include) it:
```yaml
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)
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
the [Pipelines for Merge Requests features](../merge_request_pipelines/), as mentioned
above.
the [pipelines for merge requests features](../merge_request_pipelines/).
It is [included](#include) as follows:
To [include](#include) it:
```yaml
include:
......@@ -317,7 +316,7 @@ does not block triggered pipelines.
> - 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.
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,
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](
| [`remote`](#includeremote) | Include a file from a remote URL. Must be publicly accessible. |
| [`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.
The configuration is a snapshot in time and persisted in the database. Any changes to
the referenced `.gitlab-ci.yml` file configuration is not reflected in GitLab until the next 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 persists in the database. GitLab does not reflect any changes to
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.
- Always evaluated first and merged with the content of the `.gitlab-ci.yml` file,
......@@ -367,13 +366,13 @@ include:
file: '.compliance-gitlab-ci.yml'
```
For an example of how you can include these predefined variables, and their impact on CI jobs,
see the following [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos).
For an example of how you can include these predefined variables, and the variables' impact on CI/CD jobs,
see this [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos).
#### `include:local`
`include:local` includes 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 `include:local` to include a file that is in the same repository as the `.gitlab-ci.yml` file.
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
are on the same branch.
......@@ -390,7 +389,7 @@ include:
- 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
include: '.gitlab-ci-production.yml'
......@@ -404,8 +403,9 @@ Use local includes instead of symbolic links.
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 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
include:
......@@ -413,7 +413,7 @@ include:
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
include:
......@@ -502,15 +502,15 @@ to resolve all files is 30 seconds.
#### Additional `includes` examples
There is a list of [additional `includes` examples](includes.md) available.
View [additional `includes` examples](includes.md).
## 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`
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:
......@@ -531,13 +531,13 @@ For more information, see [Available settings for `image`](../docker/using_docke
#### `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:
- 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.
- For example services, see [GitLab CI/CD Services](../services/index.md).
- Example services, see [GitLab CI/CD Services](../services/index.md).
##### `services:name`
......@@ -565,8 +565,11 @@ For more information, see [Available settings for `services`](../docker/using_do
### `script`
`script` is the only required keyword that a job needs. It's a shell script
that is executed by the runner. For example:
Use `script` to specify a shell script for the runner to execute.
All jobs except [trigger jobs](#trigger) require a `script` keyword.
For example:
```yaml
job:
......@@ -575,7 +578,7 @@ job:
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
job:
......@@ -609,7 +612,7 @@ job:
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:
Use `before_script` to define an array of commands that should run before each job,
but after [artifacts](#artifacts) are restored.
Scripts specified in `before_script` are concatenated with any scripts specified
in the main [`script`](#script), and executed together in a single shell.
Scripts you specify in `before_script` are concatenated with any scripts you specify
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
default:
......@@ -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,
including failed jobs.
If a job times out or is cancelled, the `after_script` commands are not executed.
Support for executing `after_script` commands for timed-out or cancelled jobs
[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/15603).
If a job times out or is cancelled, the `after_script` commands do not execute.
An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15603) exists to support
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:
- 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).
#### 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.
- [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:
### `stage`
`stage` is defined per-job and relies on [`stages`](#stages), which is defined
globally. Use `stage` to define which stage a job runs in, and jobs of the same
`stage` are executed in parallel (subject to [certain conditions](#use-your-own-runners)). For example:
Use `stage` to define which stage a job runs in. Jobs in the same
`stage` can execute in parallel (subject to [certain conditions](#use-your-own-runners)).
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
stages:
......@@ -751,45 +764,39 @@ is greater than `1`.
> [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.
- `.post`, which is guaranteed to always be the last stage in a pipeline.
- `.pre` is guaranteed to always be the first 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`.
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:
You can't change the order of `.pre` and `.post`, even if you define them out of order in the `.gitlab-ci.yml` file.
For example, the following configurations are equivalent:
- Configured in order:
```yaml
stages:
```yaml
stages:
- .pre
- a
- b
- .post
```
- Configured out of order:
```
```yaml
stages:
```yaml
stages:
- a
- .pre
- b
- .post
```
- Not explicitly configured:
```
```yaml
stages:
```yaml
stages:
- a
- b
```
```
### `extends`
......@@ -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
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:
- 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
#### Merge details
`extends` is able to merge hashes but not arrays.
The algorithm used for merge is "closest scope wins", so
You can use `extends` to merge hashes but not arrays.
The algorithm used for merge is "closest scope wins," so
keys from the last member always override anything defined on other
levels. For example:
......@@ -923,7 +930,7 @@ 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"`.
- `tags: ['docker']` overwrites `tags: ['production']`.
......@@ -935,8 +942,8 @@ Note that in the example above:
To reuse configuration from different configuration files,
combine `extends` and [`include`](#include).
In this example, a `script` is defined in the `included.yml` file.
Then, in the `.gitlab-ci.yml` file, you use `extends` to refer
In the following example, a `script` is defined in the `included.yml` file.
Then, in the `.gitlab-ci.yml` file, `extends` refers
to the contents of the `script`:
- `included.yml`:
......@@ -961,11 +968,11 @@ to the contents of the `script`:
> [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.
If included, the job also has [certain attributes](#rules-attributes)
The job can also have [certain attributes](#rules-attributes)
added to it.
`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:
`when: always`.
- 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
job:
......@@ -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
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
can run.
......@@ -1164,12 +1171,11 @@ runs in all cases except merge requests.
#### `rules:if`
`rules:if` clauses determine whether or not jobs are added to a pipeline by evaluating
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:
Use `rules:if` clauses to specify when to add a job to a pipeline:
- "If this rule evaluates to true, add the job" (default).
- "If this rule evaluates to true, do not add the job" (by adding `when: never`).
- If an `if` statement is true, add the job to the pipeline.
- If an `if` statement is true, but it's combined with `when: never`, do not add the job to the pipeline.
- If no `if` statements are true, do not add the job to the pipeline.
`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
......@@ -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. |
| `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
job:
......@@ -1239,11 +1247,8 @@ job:
- if: '$CI_PIPELINE_SOURCE == "push"'
```
This 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.
Another example:
The following 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.
```yaml
job:
......@@ -1253,9 +1258,6 @@ job:
- 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:
- `if: $CI_COMMIT_TAG`: If changes are pushed for a tag.
......@@ -1272,11 +1274,11 @@ Other commonly used variables for `if` clauses:
#### `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.
`rules: changes` works exactly 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
`rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychangesexceptchanges).
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`
with merge request pipelines:
......@@ -1299,7 +1301,7 @@ In this example:
- 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,
change the `if:` clause in the example above to:
change the `if:` clause in the previous example to:
```yaml
rules:
......@@ -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.
> - [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:
```yaml
......@@ -1334,7 +1336,7 @@ docker build:
- $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
`$` 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
> [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
as files in the repository.
Use `exists` to run a job when certain files exist 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
job:
......@@ -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
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
[`allow_failure`](#allow_failure) option, and is only applied when the job is
triggered by the particular rule.
[`allow_failure`](#allow_failure) option, and is only applied when
the particular rule triggers the job.
```yaml
job:
......@@ -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.
> - [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:
......@@ -1476,14 +1478,14 @@ to add jobs to pipelines, use [`rules`](#rules).
1. `except` defines the names of branches and tags the job does
**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
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 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** |
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
......@@ -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`
from running on scheduled pipelines.
In the example below, `job` runs only for refs that start with `issue-`,
whereas all branches are skipped:
In the following example, `job` runs only for refs that start with `issue-`.
All branches are skipped:
```yaml
job:
......@@ -1517,8 +1519,8 @@ job:
- branches
```
Pattern matching is case-sensitive by default. Use `i` flag modifier, like
`/pattern/i` to make a pattern case-insensitive:
Pattern matching is case-sensitive by default. Use the `i` flag modifier, like
`/pattern/i`, to make a pattern case-insensitive:
```yaml
job:
......@@ -1530,8 +1532,8 @@ job:
- branches
```
In this 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):
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):
```yaml
job:
......@@ -1542,8 +1544,7 @@ job:
- schedules
```
Use the repository path to have jobs executed only for the parent
repository and not forks:
To execute jobs only for the parent repository and not forks:
```yaml
job:
......@@ -1554,11 +1555,11 @@ job:
- /^release/.*$/@gitlab-org/gitlab
```
The above example runs `job` for all branches on `gitlab-org/gitlab`,
except `master` and those with names prefixed with `release/`.
This example runs `job` for all branches on `gitlab-org/gitlab`,
except `master` and branches that start with `release/`.
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:
......@@ -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)`
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 `variables` keyword matches.
......@@ -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)`
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.
- There are changes to the `README.md` file in the root directory of the repository.
......@@ -1679,7 +1680,7 @@ test:
The `refs` strategy can take the same values as the
[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:
```yaml
......@@ -1696,7 +1697,7 @@ deploy:
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:
```yaml
......@@ -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,
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:
- The `Dockerfile` file.
......@@ -1864,7 +1865,7 @@ docker build 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/**/*`
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.
> - 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.
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).
You can ignore stage ordering and run some jobs without waiting for others to complete.
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
linux:build:
......@@ -1937,20 +1947,6 @@ production:
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
- If `needs:` is set to point to a job that is not instantiated
......@@ -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,
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).
- 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.
##### Changing the `needs:` job limit **(FREE SELF)**
......@@ -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
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:
```yaml
......@@ -2013,7 +2009,7 @@ rubocop:
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:
- 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
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.
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:
```yaml
......@@ -2153,7 +2149,7 @@ available for the project.
When you register a runner, you can specify the runner's tags, for
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.
```yaml
......@@ -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
"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
`allow_failure: true`:
......@@ -2269,7 +2265,12 @@ The valid values of `when` are:
- With [`rules`](#rules), don't execute job.
- 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
stages:
......@@ -2308,13 +2309,6 @@ cleanup_job:
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`
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:
```
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
this list can trigger this manual job, as well as GitLab administrators
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
### `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.
If `cache` is defined outside the scope of jobs, it's set
......@@ -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
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:
```yaml
......@@ -2808,7 +2802,7 @@ cache:
- 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
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`
......@@ -2942,7 +2936,7 @@ To do so, add `policy: push` to the job.
### `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).
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
The `retry` value must be a positive integer, from `0` to `2`
(two retries maximum, three runs in total).
This example retries all failure cases:
The following example retries all failure cases:
```yaml
test:
......@@ -3584,7 +3578,7 @@ deploystacks:
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`:
```plaintext
......@@ -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
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
trigger_job:
trigger:
......@@ -3776,10 +3774,6 @@ trigger_job:
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
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
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
stages:
......@@ -3832,13 +3831,6 @@ step-3:
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`
> [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.
[`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.
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
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
......@@ -3926,7 +3918,7 @@ deployment:
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
finishes.
......@@ -3934,7 +3926,7 @@ finishes.
> [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:
......@@ -3945,18 +3937,18 @@ These keywords are supported:
- [`milestones`](#releasemilestones) (optional)
- [`released_at`](#releasereleased_at) (optional)
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.
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.
#### `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
image: registry.gitlab.com/gitlab-org/release-cli:latest
```
#### Script
#### `script`
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
......@@ -3989,11 +3981,12 @@ android-release:
#### `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.
For example, when creating a Release from a Git tag:
For example, when creating a release from a Git tag:
```yaml
job:
......@@ -4012,17 +4005,17 @@ job:
description: 'Release description'
```
- 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.
- 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.
- The `release` section executes after the `script` tag and before the `after_script`.
#### `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`
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.
##### Read description from a file
......@@ -4060,8 +4053,7 @@ released_at: '2021-03-15T08:00:00Z'
#### Complete example for `release`
Combining the individual examples given above for `release` results in the following
code snippets. There are two options, depending on how you generate the
If you combine the previous examples for `release`, you get two options, depending on how you generate the
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
......@@ -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).
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
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
> [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.
The value of each secret is saved in a temporary file. This file's path is stored in these
variables.
......@@ -4164,7 +4156,8 @@ variables.
> [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
[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
......@@ -4202,14 +4195,13 @@ job:
### `pages`
`pages` is a special job that uploads static content to GitLab that
is then published as a website. It has a special syntax, so the two
requirements below must be met:
Use `pages` to upload static content to GitLab. The content
is then published as a website. You must:
- Any static content must be placed under a `public/` directory.
- `artifacts` with a path to the `public/` directory must be defined.
- Place any static content in a `public/` directory.
- 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/` to itself in an infinite loop:
......@@ -4227,14 +4219,14 @@ pages:
- 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`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9.
You can disable inheritance of globally defined defaults
and variables with the `inherit:` keyword.
Use `inherit:` to control inheritance of globally-defined defaults
and variables.
To enable or disable the inheritance of all `default:` or `variables:` keywords, use:
......@@ -4263,7 +4255,7 @@ inherit:
- VARIABLE2
```
In the example below:
In the following example:
- `rubocop`:
- inherits: Nothing.
......@@ -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.
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):
```yaml
......@@ -4379,7 +4371,7 @@ 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_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
You can also use variables to configure how many times a runner
[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
of the code in the `.gitlab-ci.yml` file.
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
be used over these special YAML features.
In most cases, the [`extends` keyword](#extends) is more user friendly and you should
use it when possible.
You can use YAML anchors to merge YAML arrays.
......@@ -4445,8 +4437,8 @@ test2:
```
`&` sets up the name of the anchor (`job_configuration`), `<<` means "merge the
given hash into the current one", and `*` includes the named anchor
(`job_configuration` again). The expanded version of the example above is:
given hash into the current one," and `*` includes the named anchor
(`job_configuration` again). The expanded version of this example is:
```yaml
.job_template:
......@@ -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
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:
```yaml
......@@ -4606,7 +4598,7 @@ job_no_git_strategy:
### 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:
```yaml
......@@ -4625,7 +4617,7 @@ GitLab CI/CD. In the following example, `.hidden_job` is ignored:
```
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.
### `!reference` tags
......@@ -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
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:
- `setup.yml`:
......@@ -4666,7 +4658,7 @@ reused in the `test` job:
- !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.
```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