Skip to content

G
gitlab-ce
Commit 8d687c51 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'docs/edit-rules-docs' into 'master' 

Edit to new rules documentation

See merge request gitlab-org/gitlab-ce!32244
parents 72298390 1215b501
Hide whitespace changes
Inline Side-by-side
Showing with 59 additions and 33 deletions
doc/ci/yaml/README.md
View file @ 8d687c51
......@@ -100,7 +100,7 @@ The following table lists available parameters for jobs:
| [`stage`](#stage) | Defines a job stage (default: `test`). |
| [`only`](#onlyexcept-basic) | Limit when jobs are created. Also available: [`only:refs`, `only:kubernetes`, `only:variables`, and `only:changes`](#onlyexcept-advanced). |
| [`except`](#onlyexcept-basic) | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced). |
| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a build and whether or not it is created. May not be used alongside `only`/`except`.
| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it is created. May not be used alongside `only`/`except`. |
| [`tags`](#tags) | List of tags which are used to select Runner. |
| [`allow_failure`](#allow_failure) | Allow job to fail. Failed job doesn't contribute to commit status. |
| [`when`](#when) | When to run job. Also available: `when:manual` and `when:delayed`. |
......@@ -113,7 +113,7 @@ The following table lists available parameters for jobs:
| [`parallel`](#parallel) | How many instances of a job should be run in parallel. |
| [`trigger`](#trigger-premium) | Defines a downstream pipeline trigger. |
| [`include`](#include) | Allows this job to include external YAML files. Also available: `include:local`, `include:file`, `include:template`, and `include:remote`. |
| [`extends`](#extends) | Configuration entries that this job is going to inherit from. |
| [`extends`](#extends) | Configuration entries that this job is going to inherit from. |
| [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. |
| [`variables`](#variables) | Define job variables on a job level. |
......@@ -693,31 +693,41 @@ and triggers the `docker build service one` job.
### `rules`
Using `rules` allows for a list of individual rule objects to be evaluated
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29011) in GitLab 12.3.
`rules` allows for a list of individual rule objects to be evaluated
*in order*, until one matches and dynamically provides attributes to the job.
Available rule clauses include:
- `if` (similar to [`only:variables`](#onlyvariablesexceptvariables)).
- `changes` (same as [`only:changes`](#onlychangesexceptchanges)).
- [`if`](#rulesif)
(similar to [`only:variables`](#onlyvariablesexceptvariables)).
- [`changes`](#ruleschanges)
(same as [`only:changes`](#onlychangesexceptchanges)).
For example, using `if`:
For example, using `if`. This configuration specifies that `job` should be built
and run for every pipeline on merge requests targeting `master`, regardless of
the status of other builds:
```yaml
job:
script: "echo Hello, Rules!"
rules:
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH == "master"' # This rule will be evaluated
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH == "master"'
when: always
- if: '$VAR =~ /pattern/' # This rule will only be evaluated if the first does not match
- if: '$VAR =~ /pattern/'
when: manual
- when: on_success # A Rule entry with no conditional clauses evaluates to true. If neither of the first two Rules match, this one will and set job:when to "on_success"
- when: on_success
```
If the first rule does not match, further rules will be evaluated sequentially
until a match is found. The above configuration will specify that `job` should
be built and run for every pipeline on merge requests targeting `master`,
regardless of the status of other builds.
In this example, if the first rule:
- Matches, the job will be given the `when:always` attribute.
- Does not match, the second and third rules will be evaluated sequentially
until a match is found. That is, the job will be given either the:
- `when: manual` attribute if the second rule matches.
- `when: on_success` attribute if the second rule does not match. The third
rule will always match when reached because it has no conditional clauses.
#### `rules:if`
......@@ -744,10 +754,9 @@ at all, the behavior defaults to `job:when`, which continues to default to
#### `rules:changes`
`changes` works exactly the same way as [`only`/`except`](#onlychangesexceptchanges),
accepting an array of paths. The following configuration configures a job to be
run manually if `Dockerfile` has changed OR `$VAR == "string value"`. Otherwise
it is set to `when:on_success` by the last rule, where 0 clauses evaluate as
vacuously true.
accepting an array of paths.
For example:
```yaml
docker build:
......@@ -762,12 +771,20 @@ docker build:
```
#### Complex Rule Clauses
In this example, a job either set to:
- Run manually if `Dockerfile` has changed OR `$VAR == "string value"`.
- `when:on_success` by the last rule, where no earlier clauses evaluate to true.
#### Complex rule clauses
To conjoin `if` and `changes` clauses with an AND, use them in the same rule.
Here we run the job manually if `Dockerfile` or any file in `docker/scripts/`
has changed AND `$VAR == "string value"`. Otherwise, the job will not be
included in the pipeline.
In the following example:
- We run the job manually if `Dockerfile` or any file in `docker/scripts/`
has changed AND `$VAR == "string value"`.
- Otherwise, the job will not be included in the pipeline.
```yaml
docker build:
......@@ -781,18 +798,27 @@ docker build:
# - when: never would be redundant here, this is implied any time rules are listed.
```
The only clauses currently available are `if` and `changes`. Keywords such as
`branches` or `refs` that are currently available for `only`/`except` are not
yet available in `rules` as they are being individually considered for their
usage and behavior in the newer context.
The only clauses currently available are:
- `if`
- `changes`
Keywords such as `branches` or `refs` that are currently available for
`only`/`except` are not yet available in `rules` as they are being individually
considered for their usage and behavior in this context.
#### Permitted attributes
The only job attributes currently set by `rules` are `when` and `start_in`, if
`when` is set to `delayed`. A job will be included in a pipeline if `when` is
evaluated to any value except `never`.
The only job attributes currently set by `rules` are:
- `when`.
- `start_in`, if `when` is set to `delayed`.
A job will be included in a pipeline if `when` is evaluated to any value
except `never`.
Delayed jobs require a `start_in` value, so rule objects do as well. For example:
Delayed jobs require a `start_in` value, so rule objects do as well. For
example:
```yaml
docker build:
......@@ -806,9 +832,9 @@ docker build:
```
Additional Job configuration may be added to rules in the future, if something
useful isn't available, please open an issue on
[Gitlab CE](https://www.gitlab.com/gitlab-org/gitlab-ce/issues).
Additional job configuration may be added to rules in the future. If something
useful isn't available, please
[open an issue](https://www.gitlab.com/gitlab-org/gitlab-ce/issues).
### `tags`
......@@ -1801,7 +1827,7 @@ and bring back the old behavior.
### `needs`
> - Introduced in GitLab 12.2.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/47063) in GitLab 12.2.
> - In GitLab 12.3, maximum number of jobs in `needs` array raised from five to 50.
The `needs:` keyword enables executing jobs out-of-order, allowing you to implement
......
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