Commit c4416265 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs/ci-yaml-only-except-complex' into 'master'

Refactor the only and except complex section

See merge request gitlab-org/gitlab-ce!23792
parents 9403faf2 2043ec37
......@@ -402,7 +402,7 @@ job:
script: echo 'test'
```
is translated to
is translated to:
```yaml
job:
......@@ -412,49 +412,64 @@ job:
## `only` and `except` (complex)
> `refs` and `kubernetes` policies introduced in GitLab 10.0
>
> `variables` policy introduced in 10.7
>
> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in 11.4
> - `refs` and `kubernetes` policies introduced in GitLab 10.0.
> - `variables` policy introduced in GitLab 10.7.
> - `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in GitLab 11.4.
CAUTION: **Warning:**
This an _alpha_ feature, and it is subject to change at any time without
prior notice!
Since GitLab 10.0 it is possible to define a more elaborate only/except job
policy configuration.
GitLab supports both simple and complex strategies, so it's possible to use an
array and a hash configuration scheme.
GitLab now supports both, simple and complex strategies, so it is possible to
use an array and a hash configuration scheme.
Four keys are available:
Four keys are now available: `refs`, `kubernetes` and `variables` and `changes`.
- `refs`
- `variables`
- `changes`
- `kubernetes`
### `refs` and `kubernetes`
If you use multiple keys under `only` or `except`, they act as an AND. The logic is:
Refs strategy equals to simplified only/except configuration, whereas
kubernetes strategy accepts only `active` keyword.
> (any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active)
### `only:variables`
### `only:refs` and `except:refs`
`variables` keyword is used to define variables expressions. In other words
you can use predefined variables / project / group or
environment-scoped variables to define an expression GitLab is going to
evaluate in order to decide whether a job should be created or not.
The `refs` strategy can take the same values as the
[simplified only/except configuration](#only-and-except-simplified).
See the example below. Job is going to be created only when pipeline has been
scheduled or runs for a `master` branch, and only if kubernetes service is
active in the project.
In the example below, the `deploy` job is going to be created only when the
pipeline has been [scheduled][schedules] or runs for the `master` branch:
```yaml
job:
deploy:
only:
refs:
- master
- schedules
```
### `only:kubernetes` and `except:kubernetes`
The `kubernetes` strategy accepts only the `active` keyword.
In the example below, the `deploy` job is going to be created only when the
Kubernetes service is active in the project:
```yaml
deploy:
only:
kubernetes: active
```
### `only:variables` and `except:variables`
The `variables` keyword is used to define variables expressions. In other words,
you can use predefined variables / project / group or
environment-scoped variables to define an expression GitLab is going to
evaluate in order to decide whether a job should be created or not.
Examples of using variables expressions:
```yaml
......@@ -468,7 +483,7 @@ deploy:
- $STAGING
```
Another use case is exluding jobs depending on a commit message _(added in 11.0)_:
Another use case is excluding jobs depending on a commit message:
```yaml
end-to-end:
......@@ -478,11 +493,11 @@ end-to-end:
- $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
```
Learn more about variables expressions on [a separate page][variables-expressions].
Learn more about [variables expressions](../variables/README.md#variables-expressions).
### `only:changes`
### `only:changes` and `except:changes`
Using `changes` keyword with `only` or `except` makes it possible to define if
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.
For example:
......@@ -499,13 +514,13 @@ docker build:
```
In the scenario above, if you are pushing multiple commits to GitLab to an
existing branch, GitLab creates and triggers `docker build` job, provided that
existing branch, GitLab creates and triggers the `docker build` job, provided that
one of the commits contains changes to either:
- The `Dockerfile` file.
- Any of the files inside `docker/scripts/` directory.
- Any of the files and subfolders inside `dockerfiles` directory.
- Any of the files with `rb`, `py`, `sh` extensions inside `more_scripts` directory.
- Any of the files and subdirectories inside the `dockerfiles` directory.
- Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory.
CAUTION: **Warning:**
There are some caveats when using this feature with new branches and tags. See
......@@ -674,7 +689,7 @@ Manual actions are a special type of job that are not executed automatically,
they need to be explicitly started by a user. An example usage of manual actions
would be a deployment to a production environment. Manual actions can be started
from the pipeline, job, environment, and deployment views. Read more at the
[environments documentation][env-manual].
[environments documentation](../environments.md#manually-deploying-to-environments).
Manual actions can be either optional or blocking. Blocking manual actions will
block the execution of the pipeline at the stage this action is defined in. It's
......@@ -2195,19 +2210,14 @@ try to quote them, or change them to a different form (e.g., `/bin/true`).
## Examples
Visit the [examples README][examples] to see a list of examples using GitLab
CI with various languages.
See a [list of examples](../examples/README.md "CI/CD examples") for using
GitLab CI/CD with various languages.
[env-manual]: ../environments.md#manually-deploying-to-environments
[examples]: ../examples/README.md
[ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323
[environment]: ../environments.md
[ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669
[variables]: ../variables/README.md
[ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983
[ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447
[ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909
[schedules]: ../../user/project/pipelines/schedules.md
[variables-expressions]: ../variables/README.md#variables-expressions
[ee]: https://about.gitlab.com/gitlab-ee/
[gitlab-versions]: https://about.gitlab.com/products/
[environment]: ../environments.md "CI/CD environments"
[schedules]: ../../user/project/pipelines/schedules.md "Pipelines schedules"
[variables]: ../variables/README.md "CI/CD variables"
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