Merge branch 'docs/gb/improve-pipeline-variables-expressions-docs' into 'master'
Improve docs about pipeline variables expressions Closes #44786 See merge request gitlab-org/gitlab-ce!18195
This commit is contained in:
commit
861fbc37e0
|
@ -247,10 +247,19 @@ declaring their names dynamically in `.gitlab-ci.yml`. Dynamic environments is
|
|||
the basis of [Review apps](review_apps/index.md).
|
||||
|
||||
>**Note:**
|
||||
The `name` and `url` parameters can use any of the defined CI variables,
|
||||
The `name` and `url` parameters can use most of the defined CI variables,
|
||||
including predefined, secure variables and `.gitlab-ci.yml`
|
||||
[`variables`](yaml/README.md#variables).
|
||||
You however cannot use variables defined under `script` or on the Runner's side.
|
||||
[`variables`](yaml/README.md#variables). You however cannot use variables
|
||||
defined under `script` or on the Runner's side. There are other variables that
|
||||
are unsupported in environment name context:
|
||||
- `CI_JOB_ID`
|
||||
- `CI_JOB_TOKEN`
|
||||
- `CI_BUILD_ID`
|
||||
- `CI_BUILD_TOKEN`
|
||||
- `CI_REGISTRY_USER`
|
||||
- `CI_REGISTRY_PASSWORD`
|
||||
- `CI_REPOSITORY_URL`
|
||||
- `CI_ENVIRONMENT_URL`
|
||||
|
||||
GitLab Runner exposes various [environment variables][variables] when a job runs,
|
||||
and as such, you can use them as environment names. Let's add another job in
|
||||
|
|
|
@ -454,8 +454,8 @@ export CI_REGISTRY_PASSWORD="longalfanumstring"
|
|||
> Variables expressions were added in GitLab 10.7.
|
||||
|
||||
It is possible to use variables expressions with only / except policies in
|
||||
`.gitlab-ci.yml`. By using this approach you can limit what builds are going to
|
||||
be created within a pipeline after pushing code to GitLab.
|
||||
`.gitlab-ci.yml`. By using this approach you can limit what jobs are going to
|
||||
be created within a pipeline after pushing a code to GitLab.
|
||||
|
||||
This is particularly useful in combination with secret variables and triggered
|
||||
pipeline variables.
|
||||
|
@ -470,22 +470,21 @@ deploy:
|
|||
- $STAGING
|
||||
```
|
||||
|
||||
Each provided variables expression is going to be evaluated before creating
|
||||
a pipeline.
|
||||
Each expression provided is going to be evaluated before creating a pipeline.
|
||||
|
||||
If any of the conditions in `variables` evaluates to truth when using `only`,
|
||||
a new job is going to be created. If any of the expressions evaluates to truth
|
||||
when `except` is being used, a job is not going to be created.
|
||||
|
||||
This follows usual rules for `only` / `except` policies.
|
||||
This follows usual rules for [`only` / `except` policies][builds-policies].
|
||||
|
||||
### Supported syntax
|
||||
|
||||
Below you can find currently supported syntax reference:
|
||||
Below you can find supported syntax reference:
|
||||
|
||||
1. Equality matching using a string
|
||||
|
||||
Example: `$VARIABLE == "some value"`
|
||||
> Example: `$VARIABLE == "some value"`
|
||||
|
||||
You can use equality operator `==` to compare a variable content to a
|
||||
string. We support both, double quotes and single quotes to define a string
|
||||
|
@ -494,26 +493,62 @@ Below you can find currently supported syntax reference:
|
|||
|
||||
1. Checking for an undefined value
|
||||
|
||||
It sometimes happens that you want to check whether variable is defined or
|
||||
not. To do that, you can compare variable to `null` value, like
|
||||
> Example: `$VARIABLE == null`
|
||||
|
||||
It sometimes happens that you want to check whether a variable is defined
|
||||
or not. To do that, you can compare a variable to `null` keyword, like
|
||||
`$VARIABLE == null`. This expression is going to evaluate to truth if
|
||||
variable is not set.
|
||||
variable is not defined.
|
||||
|
||||
1. Checking for an empty variable
|
||||
|
||||
> Example: `$VARIABLE == ""`
|
||||
|
||||
If you want to check whether a variable is defined, but is empty, you can
|
||||
simply compare it against an empty string, like `$VAR == ''`.
|
||||
|
||||
1. Comparing two variables
|
||||
|
||||
It is possible to compare two variables. `$VARIABLE_1 == $VARIABLE_2`.
|
||||
> Example: `$VARIABLE_1 == $VARIABLE_2`
|
||||
|
||||
It is possible to compare two variables. This is going to compare values
|
||||
of these variables.
|
||||
|
||||
1. Variable presence check
|
||||
|
||||
> Example: `$STAGING`
|
||||
|
||||
If you only want to create a job when there is some variable present,
|
||||
which means that it is defined and non-empty, you can simply use
|
||||
variable name as an expression, like `$STAGING`. If `$STAGING` variable
|
||||
is defined, and is non empty, expression will evaluate to truth.
|
||||
`$STAGING` value needs to a string, with length higher than zero.
|
||||
Variable that contains only whitespace characters is not an empty variable.
|
||||
|
||||
### Unsupported predefined variables
|
||||
|
||||
Because GitLab evaluates variables before creating jobs, we do not support a
|
||||
few variables that depend on persistence layer, like `$CI_JOB_ID`.
|
||||
|
||||
Environments (like `production` or `staging`) are also being created based on
|
||||
what jobs pipeline consists of, thus some environment-specific variables are
|
||||
not supported as well.
|
||||
|
||||
We do not support variables containing tokens because of security reasons.
|
||||
|
||||
You can find a full list of unsupported variables below:
|
||||
|
||||
- `CI_JOB_ID`
|
||||
- `CI_JOB_TOKEN`
|
||||
- `CI_BUILD_ID`
|
||||
- `CI_BUILD_TOKEN`
|
||||
- `CI_REGISTRY_USER`
|
||||
- `CI_REGISTRY_PASSWORD`
|
||||
- `CI_REPOSITORY_URL`
|
||||
- `CI_ENVIRONMENT_URL`
|
||||
|
||||
These variables are also not supported in a contex of a
|
||||
[dynamic environment name][dynamic-environments].
|
||||
|
||||
[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 "Simple protection of CI secret variables"
|
||||
[eep]: https://about.gitlab.com/products/ "Available only in GitLab Premium"
|
||||
|
@ -525,3 +560,5 @@ Below you can find currently supported syntax reference:
|
|||
[triggered]: ../triggers/README.md
|
||||
[triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger
|
||||
[subgroups]: ../../user/group/subgroups/index.md
|
||||
[builds-policies]: ../yaml/README.md#only-and-except-complex
|
||||
[dynamic-environments]: ../environments.md#dynamic-environments
|
||||
|
|
|
@ -354,7 +354,7 @@ deploy:
|
|||
- $STAGING
|
||||
```
|
||||
|
||||
Learn more about variables expressions on a separate page.
|
||||
Learn more about variables expressions on [a separate page][variables-expressions].
|
||||
|
||||
## `tags`
|
||||
|
||||
|
@ -1574,3 +1574,4 @@ CI with various languages.
|
|||
[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
|
||||
|
|
Loading…
Reference in New Issue