Skip to content

G
gitlab-ce
Commit 81817878 authored by Marcel Amirault's avatar Marcel Amirault
Browse files
Options

Move variable expressions details to job control doc 

Variable expressions can only ever be used with rules,
only, or except, so we should document them together.
parent 9c4698dc
Hide whitespace changes
Inline Side-by-side
Showing with 117 additions and 154 deletions
doc/ci/jobs/job_control.md
View file @ 81817878
......@@ -73,7 +73,7 @@ end-to-end:
- $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
```
You can use [parentheses](../variables/README.md#parentheses) with `&&` and `||`
You can use [parentheses](#group-variable-expressions-together-with-parentheses) with `&&` and `||`
to build more complicated variable expressions:
```yaml
......@@ -318,3 +318,114 @@ this feature flag again:
```ruby
Feature.enable(:allow_unsafe_ruby_regexp)
```
## CI/CD variable expressions
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyvariables--exceptvariables)
> - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules)
Use variable expressions to control which jobs are created in a pipeline after changes
are pushed to GitLab. You can use variable expressions with:
- [`rules:if`](../yaml/README.md#rules).
- [`only:variables` and `except:variables`](../yaml/README.md#onlyvariables--exceptvariables).
For example, with `rules:if`:
```yaml
job1:
variables:
VAR1: "variable1"
script:
- echo "Test variable comparison
rules:
- if: $VAR1 == "variable1"
```
### Compare a variable to a string
You can use the equality operators `==` and `!=` to compare a variable with a
string. Both single quotes and double quotes are valid. The order doesn't matter,
so the variable can be first, or the string can be first. For example:
- `if: $VARIABLE == "some value"`
- `if: $VARIABLE != "some value"`
- `if: "some value" == $VARIABLE`
### Compare two variables
You can compare the values of two variables. For example:
- `if: $VARIABLE_1 == $VARIABLE_2`
- `if: $VARIABLE_1 != $VARIABLE_2`
### Check if a variable is undefined
You can compare a variable to the `null` keyword to see if it is defined. For example:
- `if: $VARIABLE == null`
- `if: $VARIABLE != null`
### Check if a variable is empty
You can check if a variable is defined but empty. For example:
- `if: $VARIABLE == ""`
- `if: $VARIABLE != ""`
### Check if a variable exists
You can check for the existence of a variable by using just the variable name in
the expression. The variable must not be empty. For example:
- `if: $VARIABLE`
### Compare a variable to a regex pattern
You can do regex pattern matching on variable values with the `=~` and `!~` operators.
Variable pattern matching with regular expressions uses the
[RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax).
Expressions evaluate as `true` if:
- Matches are found when using `=~`.
- Matches are *not* found when using `!~`.
For example:
- `$VARIABLE =~ /^content.*/`
- `$VARIABLE_1 !~ /^content.*/`
Pattern matching is case-sensitive by default. Use the `i` flag modifier to make a
pattern case-insensitive. For example: `/pattern/i`.
### Join variable expressions together with `&&` or `||`
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62867) in GitLab 12.0
You can join multiple expressions using `&&` (and) or `||` (or), for example:
- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3`
- `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3`
The precedence of operators follows the [Ruby 2.5 standard](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html),
so `&&` is evaluated before `||`.
#### Group variable expressions together with parentheses
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/238174) in GitLab 13.5.
You can use parentheses to group expressions together. Parentheses take precedence over
`&&` and `||`, so expressions enclosed in parentheses are evaluated first, and the
result is used for the rest of the expression.
You can nest parentheses to create complex conditions, and the inner-most expressions
in parentheses are evaluated first.
For example:
- `($VARIABLE1 =~ /^content.*/ || $VARIABLE2) && ($VARIABLE3 =~ /thing$/ || $VARIABLE4)`
- `($VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/) && $VARIABLE3`
- `$CI_COMMIT_BRANCH == "my-branch" || (($VARIABLE1 == "thing" || $VARIABLE2 == "thing") && $VARIABLE3)`
doc/ci/variables/README.md
View file @ 81817878
......@@ -647,154 +647,6 @@ with `K8S_SECRET_`.
CI/CD variables with multi-line values are not supported.
## CI/CD variable expressions
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyvariables--exceptvariables)
> - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules)
Use variable expressions to limit which jobs are created
in a pipeline after changes are pushed to GitLab.
In `.gitlab-ci.yml`, variable expressions work with both:
- [`rules`](../yaml/README.md#rules), which is the recommended approach, and
- [`only` and `except`](../yaml/README.md#only--except), which are candidates for deprecation.
This is particularly useful in combination with variables and triggered
pipeline variables.
```yaml
deploy:
script: cap staging deploy
environment: staging
only:
variables:
- $RELEASE == "staging"
- $STAGING
```
Each expression provided is evaluated before a pipeline is created.
If any of the conditions in `variables` evaluates to true when using `only`,
a new job is created. If any of the expressions evaluates to true
when `except` is being used, a job is not created.
This follows the usual rules for [`only` / `except` policies](../yaml/README.md#onlyvariables--exceptvariables).
### Syntax of CI/CD variable expressions
Below you can find supported syntax reference.
#### Equality matching using a string
Examples:
- `$VARIABLE == "some value"`
- `$VARIABLE != "some value"` (introduced in GitLab 11.11)
You can use equality operator `==` or `!=` to compare a variable content to a
string. We support both, double quotes and single quotes to define a string
value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'`
are supported. `"some value" == $VARIABLE` is correct too.
#### Checking for an undefined value
Examples:
- `$VARIABLE == null`
- `$VARIABLE != null` (introduced in GitLab 11.11)
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 evaluates to true if
variable is not defined when `==` is used, or to false if `!=` is used.
#### Checking for an empty variable
Examples:
- `$VARIABLE == ""`
- `$VARIABLE != ""` (introduced in GitLab 11.11)
To check if a variable is defined but empty, compare it to:
- An empty string: `$VARIABLE == ''`
- A non-empty string: `$VARIABLE != ""`
#### Comparing two variables
Examples:
- `$VARIABLE_1 == $VARIABLE_2`
- `$VARIABLE_1 != $VARIABLE_2` (introduced in GitLab 11.11)
It is possible to compare two variables. This compares values
of these variables.
#### Variable presence check
Example: `$STAGING`
To create a job when there is some variable present, meaning it is defined and non-empty,
use the variable name as an expression, like `$STAGING`. If the `$STAGING` variable
is defined, and is non empty, expression evaluates to `true`.
`$STAGING` value needs to be a string, with length higher than zero.
Variable that contains only whitespace characters is not an empty variable.
#### Regex pattern matching
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43601) in GitLab 11.0
Examples:
- `=~`: True if pattern is matched. Ex: `$VARIABLE =~ /^content.*/`
- `!~`: True if pattern is not matched. Ex: `$VARIABLE_1 !~ /^content.*/` ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/61900) in GitLab 11.11)
Variable pattern matching with regular expressions uses the
[RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax).
Expressions evaluate as `true` if:
- Matches are found when using `=~`.
- Matches are *not* found when using `!~`.
Pattern matching is case-sensitive by default. Use `i` flag modifier, like
`/pattern/i` to make a pattern case-insensitive.
#### Conjunction / Disjunction
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62867) in GitLab 12.0
Examples:
- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
- `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3`
- `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3`
It is possible to join multiple conditions using `&&` or `||`. Any of the otherwise
supported syntax may be used in a conjunctive or disjunctive statement.
Precedence of operators follows the
[Ruby 2.5 standard](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html),
so `&&` is evaluated before `||`.
#### Parentheses
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/238174) in GitLab 13.5.
It is possible to use parentheses to group conditions. Parentheses have the highest
precedence of all operators. Expressions enclosed in parentheses are evaluated first,
and the result is used for the rest of the expression.
Many nested parentheses can be used to create complex conditions, and the inner-most
expressions in parentheses are evaluated first. For an expression to be valid an equal
number of `(` and `)` need to be used.
Examples:
- `($VARIABLE1 =~ /^content.*/ || $VARIABLE2) && ($VARIABLE3 =~ /thing$/ || $VARIABLE4)`
- `($VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/) && $VARIABLE3`
- `$CI_COMMIT_BRANCH == "my-branch" || (($VARIABLE1 == "thing" || $VARIABLE2 == "thing") && $VARIABLE3)`
## Debug logging
> Introduced in GitLab Runner 1.7.
......
doc/ci/variables/where_variables_can_be_used.md
View file @ 81817878
......@@ -174,7 +174,7 @@ They are:
- Script execution shell.
- Not supported:
- For definitions where the ["Expansion place"](#gitlab-ciyml-file) is GitLab.
- In the `only` and `except` [variables expressions](README.md#cicd-variable-expressions).
- In the `only` and `except` [variables expressions](../jobs/job_control.md#cicd-variable-expressions).
Some of the persisted variables contain tokens and cannot be used by some definitions
due to security reasons.
......
doc/ci/yaml/README.md
View file @ 81817878
......@@ -1323,8 +1323,8 @@ Use `rules:if` clauses to specify when to add a job to a pipeline:
`rules:if` differs slightly from `only:variables` by accepting only a single
expression string per rule, rather than an array of them. Any set of expressions to be
evaluated can be [conjoined into a single expression](../variables/README.md#conjunction--disjunction)
by using `&&` or `||`, and the [variable matching operators (`==`, `!=`, `=~` and `!~`)](../variables/README.md#syntax-of-cicd-variable-expressions).
evaluated can be [conjoined into a single expression](../jobs/job_control.md#join-variable-expressions-together-with--or-)
by using `&&` or `||`, and the [variable matching operators (`==`, `!=`, `=~` and `!~`)](../jobs/job_control.md#cicd-variable-expressions).
Unlike variables in [`script`](../variables/README.md#use-cicd-variables-in-job-scripts)
sections, variables in rules expressions are always formatted as `$VARIABLE`.
......@@ -1598,7 +1598,7 @@ considered for their usage and behavior in this context. Future keyword improvem
are being discussed in our [epic for improving `rules`](https://gitlab.com/groups/gitlab-org/-/epics/2783),
where anyone can add suggestions or requests.
You can use [parentheses](../variables/README.md#parentheses) with `&&` and `||` to build more complicated variable expressions.
You can use [parentheses](../jobs/job_control.md#group-variable-expressions-together-with-parentheses) with `&&` and `||` to build more complicated variable expressions.
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3:
```yaml
......@@ -1726,7 +1726,7 @@ to a pipeline, based on the status of [CI/CD variables](../variables/README.md).
**Keyword type**: Job keyword. You can use it only as part of a job.
**Possible inputs**: An array of [CI/CD variable expressions](../variables/README.md#cicd-variable-expressions).
**Possible inputs**: An array of [CI/CD variable expressions](../jobs/job_control.md#cicd-variable-expressions).
**Example of `only: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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7