Merge branch 'docs-move-variable-expressions' into 'master'

Move variable expressions details to job control doc

See merge request gitlab-org/gitlab!63961

doc/ci/jobs/job_control.md

@@ -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

@@ -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

@@ -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

@@ -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`**: