Skip to content

G
gitlab-ce
Commit d34f68d3 authored by Suzanne Selhorn's avatar Suzanne Selhorn
Browse files
Options

Merge branch 'docs-yaml-ing-using' into 'master' 

Copy edit yaml reference doc, focusing on "using"

See merge request gitlab-org/gitlab!53121
parents 0078d8eb 5c5a29af
Show whitespace changes
Inline Side-by-side
Showing with 92 additions and 100 deletions
doc/ci/yaml/README.md
View file @ d34f68d3
......@@ -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:
- `included.yml`:
```yaml
.template:
script:
- echo Hello!
```
```
Then, in the `.gitlab-ci.yml` file:
- `.gitlab-ci.yml`:
```yaml
include: included.yml
```yaml
include: included.yml
useTemplate:
useTemplate:
image: alpine
extends: .template
```
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.
```
### `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