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: ...@@ -402,7 +402,7 @@ job:
script: echo 'test' script: echo 'test'
``` ```
is translated to is translated to:
```yaml ```yaml
job: job:
...@@ -412,49 +412,64 @@ job: ...@@ -412,49 +412,64 @@ job:
## `only` and `except` (complex) ## `only` and `except` (complex)
> `refs` and `kubernetes` policies introduced in GitLab 10.0 > - `refs` and `kubernetes` policies introduced in GitLab 10.0.
> > - `variables` policy introduced in GitLab 10.7.
> `variables` policy introduced in 10.7 > - `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in GitLab 11.4.
>
> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in 11.4
CAUTION: **Warning:** CAUTION: **Warning:**
This an _alpha_ feature, and it is subject to change at any time without This an _alpha_ feature, and it is subject to change at any time without
prior notice! prior notice!
Since GitLab 10.0 it is possible to define a more elaborate only/except job GitLab supports both simple and complex strategies, so it's possible to use an
policy configuration. array and a hash configuration scheme.
GitLab now supports both, simple and complex strategies, so it is possible to Four keys are available:
use an array and a hash configuration scheme.
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 > (any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active)
kubernetes strategy accepts only `active` keyword.
### `only:variables` ### `only:refs` and `except:refs`
`variables` keyword is used to define variables expressions. In other words The `refs` strategy can take the same values as the
you can use predefined variables / project / group or [simplified only/except configuration](#only-and-except-simplified).
environment-scoped variables to define an expression GitLab is going to
evaluate in order to decide whether a job should be created or not.
See the example below. Job is going to be created only when pipeline has been In the example below, the `deploy` job is going to be created only when the
scheduled or runs for a `master` branch, and only if kubernetes service is pipeline has been [scheduled][schedules] or runs for the `master` branch:
active in the project.
```yaml ```yaml
job: deploy:
only: only:
refs: refs:
- master - master
- schedules - 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 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: Examples of using variables expressions:
```yaml ```yaml
...@@ -468,7 +483,7 @@ deploy: ...@@ -468,7 +483,7 @@ deploy:
- $STAGING - $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 ```yaml
end-to-end: end-to-end:
...@@ -478,11 +493,11 @@ end-to-end: ...@@ -478,11 +493,11 @@ end-to-end:
- $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/ - $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. a job should be created based on files modified by a git push event.
For example: For example:
...@@ -499,13 +514,13 @@ docker build: ...@@ -499,13 +514,13 @@ docker build:
``` ```
In the scenario above, if you are pushing multiple commits to GitLab to an 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: one of the commits contains changes to either:
- The `Dockerfile` file. - The `Dockerfile` file.
- Any of the files inside `docker/scripts/` directory. - Any of the files inside `docker/scripts/` directory.
- Any of the files and subfolders inside `dockerfiles` directory. - Any of the files and subdirectories inside the `dockerfiles` directory.
- Any of the files with `rb`, `py`, `sh` extensions inside `more_scripts` directory. - Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory.
CAUTION: **Warning:** CAUTION: **Warning:**
There are some caveats when using this feature with new branches and tags. See 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, ...@@ -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 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 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 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 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 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`). ...@@ -2195,19 +2210,14 @@ try to quote them, or change them to a different form (e.g., `/bin/true`).
## Examples ## Examples
Visit the [examples README][examples] to see a list of examples using GitLab See a [list of examples](../examples/README.md "CI/CD examples") for using
CI with various languages. 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 [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 [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-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983
[ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447 [ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447
[ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909 [ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909
[schedules]: ../../user/project/pipelines/schedules.md [environment]: ../environments.md "CI/CD environments"
[variables-expressions]: ../variables/README.md#variables-expressions [schedules]: ../../user/project/pipelines/schedules.md "Pipelines schedules"
[ee]: https://about.gitlab.com/gitlab-ee/ [variables]: ../variables/README.md "CI/CD variables"
[gitlab-versions]: https://about.gitlab.com/products/
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