@@ -100,6 +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 coniditions to evaluate and determine selected attributes of a build 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`. |
...
...
@@ -690,6 +691,125 @@ In the scenario above, if a merge request is created or updated that changes
either files in `service-one` directory or the `Dockerfile`, GitLab creates
and triggers the `docker build service one` job.
### `rules`
Using `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)).
For example, using `if`:
```yaml
job:
script:"echoHello,Rules!"
rules:
-if:'$CI_MERGE_REQUEST_TARGET_BRANCH=="master"'# This rule will be evaluated
when:always
-if:'$VAR=~/pattern/'# This rule will only be evaluated if the first does not match
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"
```
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.
#### `rules:if`
`rules:if` differs slightly from `only:variables` by accepting only a single
expression string, rather than an array of them. Any set of expressions to be
evaluated should be conjoined into a single expression using `&&` or `||`. For example:
```yaml
job:
script:"echoHello,Rules!"
rules:
-if:'$CI_MERGE_REQUEST_SOURCE_BRANCH=~/^feature/&&$CI_MERGE_REQUEST_TARGET_BRANCH=="master"'# This rule will be evaluated
when:always
-if:'$CI_MERGE_REQUEST_SOURCE_BRANCH=~/^feature/'# This rule will only be evaluated if the target branch is not "master"
when:manual
-if:'$CI_MERGE_REQUEST_SOURCE_BRANCH'# If neither of the first two match but the simple presence does, we set to "on_success" by default
```
If none of the provided rules match, the job will be set to `when:never`, and
not included in the pipeline. If `rules:when` is not included in the configuration
at all, the behavior defaults to `job:when`, which continues to default to
`on_success`.
#### `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
