Skip to content

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

Copy edit yaml reference doc 

Focuses on usage of the word using that
can be improved, but also improves introductions
to examples
parent 0078d8eb
Hide whitespace changes
Inline Side-by-side
Showing with 92 additions and 100 deletions
doc/ci/yaml/README.md
View file @ 5c5a29af
......@@ -72,7 +72,7 @@ can't be used as job names:
### Reserved keywords
If you get a validation error when using specific values (for example, `true` or `false`), try to:
If you get a validation error when you use specific values (for example, `true` or `false`), try to:
- Quote them.
- Change them to a different form. For example, `/bin/true`.
......@@ -477,17 +477,16 @@ include:
#### `include:remote`
Use `include:remote` to include a file from a different location,
using HTTP/HTTPS, referenced by the full URL. The remote file must be
publicly accessible by a GET request, because authentication schemas
in the remote URL are not supported. For example:
Use `include:remote` with a full URL to include a file from a different location.
The remote file must be publicly accessible by an HTTP/HTTPS `GET` request, because
authentication in the remote URL is not supported. For example:
```yaml
include:
- remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
- remote: 'https://gitlab.com/example-project/-/raw/master/.gitlab-ci.yml'
```
All [nested includes](#nested-includes) are executed without context as a public user,
All [nested includes](#nested-includes) execute without context as a public user,
so you can only `include` public projects or templates.
#### `include:template`
......@@ -732,7 +731,7 @@ You can use special syntax in [`script`](README.md#script) sections to:
`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](#using-your-own-runners)). For example:
`stage` are executed in parallel (subject to [certain conditions](#use-your-own-runners)). For example:
```yaml
stages:
......@@ -765,7 +764,7 @@ job 5:
script: make something useful at the end of pipeline
```
#### Using your own runners
#### Use your own runners
When you use your own runners, each runner runs only one job at a time by default.
Jobs can run in parallel if they run on different runners.
......@@ -822,11 +821,16 @@ For example, the following are equivalent configuration:
> Introduced in GitLab 11.3.
`extends` defines entry names that a job that uses `extends`
inherits from.
Use `extends` to reuse configuration sections. It's an alternative to [YAML anchors](#anchors)
and is a little more flexible and readable. You can use `extends` to reuse configuration
from [included configuration files](#use-extends-and-include-together).
It's an alternative to using [YAML anchors](#anchors) and is a little
more flexible and readable:
In this example, the `rspec` job uses the configuration from the `.tests` template job.
GitLab:
- Performs a reverse deep merge based on the keys.
- Merges the `.tests` content with the `rspec` job.
- Doesn't merge the values of the keys.
```yaml
.tests:
......@@ -844,13 +848,7 @@ rspec:
- $RSPEC
```
In the example above, the `rspec` job inherits from the `.tests` template job.
GitLab performs a reverse deep merge based on the keys. GitLab:
- Merges the `rspec` contents into `.tests` recursively.
- Doesn't merge the values of the keys.
The result is this `rspec` job, where `script: rake test` is overwritten by `script: rake rspec`:
The result is this `rspec` job:
```yaml
rspec:
......@@ -863,10 +861,8 @@ rspec:
- $RSPEC
```
If you do want to include the `rake test`, see [`before_script`](#before_script) or [`after_script`](#after_script).
`.tests` in this example is a [hidden job](#hide-jobs), but it's
possible to inherit from regular jobs as well.
possible to extend configuration from regular jobs as well.
`extends` supports multi-level inheritance. You should avoid using more than three levels,
but you can use as many as eleven. The following example has two levels of inheritance:
......@@ -960,30 +956,32 @@ Note that in the example above:
- `script` does not merge, but `script: ['rake rspec']` overwrites
`script: ['echo "Hello world!"']`. You can use [YAML anchors](#anchors) to merge arrays.
#### Using `extends` and `include` together
#### Use `extends` and `include` together
`extends` works across configuration files combined with `include`.
To reuse configuration from different configuration files,
combine `extends` and [`include`](#include).
For example, if you have a local `included.yml` file:
In this example, a `script` is defined in the `included.yml` file.
Then, in the `.gitlab-ci.yml` file, you use `extends` to refer
to the contents of the `script`:
```yaml
.template:
script:
- echo Hello!
```
- `included.yml`:
Then, in the `.gitlab-ci.yml` file:
```yaml
.template:
script:
- echo Hello!
```
```yaml
include: included.yml
- `.gitlab-ci.yml`:
useTemplate:
image: alpine
extends: .template
```
```yaml
include: included.yml
This example runs a job called `useTemplate` that runs `echo Hello!` as defined in
the `.template` job, and uses the `alpine` Docker image as defined in the local job.
useTemplate:
image: alpine
extends: .template
```
### `rules`
......@@ -1052,7 +1050,7 @@ The job is not added to the pipeline:
`when: always`.
- If a rule matches, and has `when: never` as the attribute.
For example, using `if` clauses to strictly limit when jobs run:
This example uses `if` to strictly limit when jobs run:
```yaml
job:
......@@ -1064,8 +1062,6 @@ job:
- if: '$CI_PIPELINE_SOURCE == "schedule"'
```
In this example:
- If the pipeline is for a merge request, the first rule matches, and the job
is added to the [merge request pipeline](../merge_request_pipelines/index.md)
with attributes of:
......@@ -1139,7 +1135,7 @@ There are multiple ways to avoid duplicate pipelines:
or push (branch) pipelines only.
- Rewrite the rules to run the job only in very specific cases,
and avoid using a final `when:` rule:
and avoid a final `when:` rule:
```yaml
job:
......@@ -1256,7 +1252,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable:
|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). |
| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command. |
| `external` | When using CI services other than GitLab. |
| `external` | When you use CI services other than GitLab. |
| `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). |
| `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. |
......@@ -1383,7 +1379,9 @@ 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:
as files in the repository.
In this example, `job` runs if a `Dockerfile` exists anywhere in the repository:
```yaml
job:
......@@ -1408,15 +1406,14 @@ job:
Glob patterns are interpreted with Ruby [File.fnmatch](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch)
with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`.
For performance reasons, using `exists` with patterns is limited to 10,000
checks. After the 10,000th check, rules with patterned globs always match.
For performance reasons, GitLab matches a maximum of 10,000 `exists` patterns. After the 10,000th check, rules with patterned globs always match.
#### `rules:allow_failure`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8.
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 using `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.
The rule-level `rules:allow_failure` option overrides the job-level
......@@ -1532,12 +1529,10 @@ rules that use both `||` and `&&` may evaluate with an unexpected order of opera
### `only`/`except` (basic)
NOTE:
The [`rules`](#rules) syntax is an improved, more powerful solution for defining
when jobs should run or not. Consider using `rules` instead of `only/except` to get
the most out of your pipelines.
`only` and `except` are not being actively developed. To define when
to add jobs to pipelines, use [`rules`](#rules).
`only` and `except` are two keywords that set a job policy to limit when
jobs are created:
`only` and `except` are two keywords that determine when to add jobs to pipelines:
1. `only` defines the names of branches and tags the job runs for.
1. `except` defines the names of branches and tags the job does
......@@ -1557,7 +1552,7 @@ In addition, `only` and `except` can use special keywords:
| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). |
| `branches` | When the Git reference for a pipeline is a branch. |
| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/README.md) command. |
| `external` | When using CI services other than GitLab. |
| `external` | When you use CI services other than GitLab. |
| `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). |
| `merge_requests` | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
| `pipelines` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. |
......@@ -1780,7 +1775,7 @@ The `variables` keyword defines variable expressions.
These expressions determine whether or not a job should be created.
Examples of using variable expressions:
Examples of variable expressions:
```yaml
deploy:
......@@ -1819,15 +1814,14 @@ job1:
> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4.
Using the `changes` keyword with `only` or `except` makes it possible to define if
a job should be created based on files modified by a Git push event.
Use the `changes` keyword with `only` to run a job, or with `except` to skip a job,
when a Git push event modifies a file.
Use the `only:changes` policy for pipelines triggered by the following
refs only:
Use `only:changes` with pipelines triggered by the following refs only:
- `branches`
- `external_pull_requests`
- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](#using-onlychanges-with-pipelines-for-merge-requests))
- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](#use-onlychanges-with-pipelines-for-merge-requests))
WARNING:
In pipelines with [sources other than the three above](../variables/predefined_variables.md)
......@@ -1835,7 +1829,13 @@ 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.
A basic example of using `only: changes`:
In this example, when you push commits to an existing branch, the `docker build` job
runs only if any of these files change:
- The `Dockerfile` file.
- Files in the `docker/scripts/` directory.
- Files and subdirectories in the `dockerfiles` directory.
- Files with `rb`, `py`, `sh` extensions in the `more_scripts` directory.
```yaml
docker build:
......@@ -1850,21 +1850,13 @@ docker build:
- more_scripts/*.{rb,py,sh}
```
When you push commits to an existing branch,
the `docker build` job is created, but only if changes were made to any of the following:
- The `Dockerfile` file.
- Any of the files in the `docker/scripts/` directory.
- Any of the files and subdirectories in the `dockerfiles` directory.
- Any of the files with `rb`, `py`, `sh` extensions in the `more_scripts` directory.
WARNING:
If you use `only:changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds),
you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected.
you should [also use `only:merge_requests`](#use-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected.
You can also use glob patterns to match multiple files in either the root directory
of the repository, or in _any_ directory in the repository. However, they must be wrapped
in double quotes or GitLab can't parse them. For example:
in double quotes or GitLab can't parse them:
```yaml
test:
......@@ -1893,10 +1885,10 @@ the `build` job is still skipped. The job does not run for any of the files.
Read more about how to use this feature with:
- [New branches or tags *without* pipelines for merge requests](#using-onlychanges-without-pipelines-for-merge-requests).
- [Scheduled pipelines](#using-onlychanges-with-scheduled-pipelines).
- [New branches or tags *without* pipelines for merge requests](#use-onlychanges-without-pipelines-for-merge-requests).
- [Scheduled pipelines](#use-onlychanges-with-scheduled-pipelines).
##### Using `only:changes` with pipelines for merge requests
##### Use `only:changes` with pipelines for merge requests
With [pipelines for merge requests](../merge_request_pipelines/index.md),
it's possible to define a job to be created based on files modified
......@@ -1946,7 +1938,7 @@ it doesn't matter that an earlier pipeline failed because of a change that has n
When you use this configuration, ensure that the most recent pipeline
properly corrects any failures from previous pipelines.
##### Using `only:changes` without pipelines for merge requests
##### Use `only:changes` without pipelines for merge requests
Without [pipelines for merge requests](../merge_request_pipelines/index.md), pipelines
run on branches or tags that don't have an explicit association with a merge request.
......@@ -1954,14 +1946,13 @@ In this case, a previous SHA is used to calculate the diff, which is equivalent
This can result in some unexpected behavior, including:
- When pushing a new branch or a new tag to GitLab, the policy always evaluates to true.
- When pushing a new commit, the changed files are calculated using the previous commit
- When pushing a new commit, the changed files are calculated by using the previous commit
as the base SHA.
##### Using `only:changes` with scheduled pipelines
##### Use `only:changes` with scheduled pipelines
`only:changes` always evaluates as "true" in [Scheduled pipelines](../pipelines/schedules.md).
All files are considered to have "changed" when a scheduled pipeline
runs.
`only:changes` always evaluates as true in [Scheduled pipelines](../pipelines/schedules.md).
All files are considered to have changed when a scheduled pipeline runs.
### `needs`
......@@ -2056,14 +2047,11 @@ To disable directed acyclic graphs (DAG), set the limit to `0`.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.6.
When using `needs`, artifact downloads are controlled with `artifacts: true` (default) or `artifacts: false`.
In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword
with `needs` to control artifact downloads in jobs. `dependencies` is still valid
in jobs that do not use `needs`.
Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are
downloaded in jobs that use `needs`.
In the example below, the `rspec` job downloads the `build_job` artifacts, while the
`rubocop` job doesn't:
In this example, the `rspec` job downloads the `build_job` artifacts, but the
`rubocop` job does not:
```yaml
build_job:
......@@ -2085,9 +2073,11 @@ rubocop:
artifacts: false
```
Additionally, in the three syntax examples below, the `rspec` job downloads the artifacts
from all three `build_jobs`. `artifacts` is true for `build_job_1` and
**defaults** to true for both `build_job_2` and `build_job_3`.
In this example, the `rspec` job downloads the artifacts from all three `build_jobs`.
`artifacts` is:
- Set to true for `build_job_1`.
- Defaults to true for both `build_job_2` and `build_job_3`.
```yaml
rspec:
......@@ -2098,6 +2088,9 @@ rspec:
- build_job_3
```
In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword
with `needs`.
#### Cross project artifact downloads with `needs` **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.7.
......@@ -2255,10 +2248,11 @@ osx job:
### `allow_failure`
Use `allow_failure` when you want to let a job fail without impacting the rest of the CI
suite.
The default value is `false`, except for [manual](#whenmanual) jobs using the
`when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs
default to false, *including* `when: manual` jobs.
suite. The default value is `false`, except for [manual](#whenmanual) jobs that use
the `when: manual` syntax.
In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`,
*including* `when: manual` jobs.
When `allow_failure` is set to `true` and the job fails, the job shows an orange warning in the UI.
However, the logical flow of the pipeline considers the job a
......@@ -2825,7 +2819,8 @@ 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.
For example:
In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined
by the `CACHE_FALLBACK_KEY` variable:
```yaml
variables:
......@@ -2837,9 +2832,6 @@ cache:
- binaries/
```
In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined
by the `CACHE_FALLBACK_KEY` variable.
##### `cache:key:files`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5.
......@@ -3616,7 +3608,7 @@ but with different variable values for each instance of the job.
There can be from 2 to 50 jobs.
Jobs can only run in parallel if there are multiple runners, or a single runner is
[configured to run multiple jobs concurrently](#using-your-own-runners).
[configured to run multiple jobs concurrently](#use-your-own-runners).
Every job gets the same `CI_NODE_TOTAL` [environment variable](../variables/README.md#predefined-environment-variables) value, and a unique `CI_NODE_INDEX` value.
......
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