diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index cff797549ba3382c15d6be1954c52a933ba444f2..63a18e6fb530bacf193eedeb5307bee6a3b20c98 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -471,11 +471,13 @@ value you set for this specific pipeline:
 
 ## Environment variables expressions
 
-> Introduced in GitLab 10.7.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyexcept-advanced)
+> - [Expanded](https://gitlab.com/gitlab-org/gitlab/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.html#rules)
 
-It is possible to use variables expressions with only / except policies in
-`.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.
+Variable expressions can be used to limit what jobs are going to be created
+within a pipeline after pushing changes to GitLab.
+
+Originally, this was configured with [`only` and `except`](../yaml/README.html#onlyexcept-basic) in the `.gitlab-ci.yml`, but this is now deprecated. Variable expressions should now only be used with [`rules`](../yaml/README.html#rules).
 
 This is particularly useful in combination with variables and triggered
 pipeline variables.
@@ -562,12 +564,8 @@ Below you can find supported syntax reference:
 
    Examples:
 
-   - `$VARIABLE =~ /^content.*/`
-   - `$VARIABLE_1 !~ /^content.*/` (introduced in GitLab 11.11)
-
-   It is possible perform pattern matching against a variable and regular
-   expression. Expression like this evaluates to truth if matches are found
-   when using `=~`. It evaluates to truth if matches are not found when `!~` is used.
+   - `=~`: 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)
 
    Pattern matching is case-sensitive by default. Use `i` flag modifier, like
    `/pattern/i` to make a pattern case-insensitive.
@@ -582,8 +580,47 @@ Below you can find supported syntax reference:
 
    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 standard Ruby 2.5 operation
-   [precedence](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html).
+   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 `||`.
+
+### Storing regular expressions in variables
+
+It is possible to store a regular expression in a variable, to be used for pattern matching:
+
+```yaml
+variables:
+  STAGINGRELS: '/staging0|staging1/'
+
+deploy_staging:
+  script: do.sh deploy staging
+  environment: staging
+  rules:
+    - if: '$RELEASE =~ $STAGINGRELS'
+```
+
+NOTE: **Note:**
+The available regular expression syntax is limited. See [related issue](https://gitlab.com/gitlab-org/gitlab/issues/35438)
+for more details.
+
+If needed, you can use a test pipeline to determine whether a regular expression will
+work in a variable. The example below tests the `^mast.*` regular expression directly,
+as well as from within a variable:
+
+```yaml
+variables:
+  MYSTRING: 'master'
+  MYREGEX: '/^mast.*/'
+
+testdirect:
+  script: /bin/true
+  rules:
+    - if: '$MYSTRING =~ /^mast.*/'
+
+testvariable:
+  script: /bin/true
+  rules:
+    - if: '$MYSTRING =~ $MYREGEX'
+```
 
 ## Debug logging
 
@@ -595,6 +632,10 @@ output **will** contain the content of all your variables and any other
 secrets! The output **will** be uploaded to the GitLab server and made visible
 in job logs!
 
+[Some of the variables](where_variables_can_be_used.md) in the debug output
+Not all variables in the debug output are [available for use](where_variables_can_be_used.md)
+in `.gitlab-ci.yml`.
+
 By default, GitLab Runner hides most of the details of what it is doing when
 processing a job. This behavior keeps job logs short, and prevents secrets
 from being leaked into the log unless your script writes them to the screen.
diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md
index b5296f2626909e7701375357d7a3c5a9427e025c..45dae250d8ac1b2ff612159be192b16c679f51c3 100644
--- a/doc/ci/variables/where_variables_can_be_used.md
+++ b/doc/ci/variables/where_variables_can_be_used.md
@@ -32,6 +32,67 @@ There are two places defined variables can be used. On the:
 | `script`, `before_script`, `after_script`  | yes              | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment)                                                                                                                                                                                                                                                                                                                                 |
 | `only:variables:[]`, `except:variables:[]` | no               | n/a                    | The variable must be in the form of `$variable`. Not supported are the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables).                                                                                            |
 
+Not all variables shown when using [runner debugging](https://docs.gitlab.com/runner/commands/#running-in-debug-mode)
+are available for use in `.gitlab-ci.yml`.
+
+For example: if you're using [`rules`](../yaml/README.html#rules), or [`only` / `except`](../yaml/README.html#onlyexcept-basic)
+to determine whether or not jobs are created, the debug output on the shell runner
+may show the following variables, but they are not available for use in `.gitlab-ci.yml`:
+
+```
+CI_RUNNER_DESCRIPTION
+CI_RUNNER_EXECUTABLE_ARCH
+CI_RUNNER_ID
+CI_RUNNER_REVISION
+CI_RUNNER_SHORT_TOKEN
+CI_RUNNER_TAGS
+CI_RUNNER_VERSION
+CONFIG_FILE
+```
+
+Variables derived from the shell runner's environment are also not available, such as:
+
+```
+HOME
+PATH
+SHELL
+```
+
+- The following are also not available:
+
+```
+CI_BUILD_ID
+CI_BUILDS_DIR
+CI_BUILD_TOKEN
+CI_CONCURRENT_ID
+CI_CONCURRENT_PROJECT_ID
+CI_JOB_ID
+CI_JOB_TOKEN
+CI_JOB_URL
+CI_PIPELINE_ID
+CI_PIPELINE_URL
+CI_PROJECT_DIR
+CI_REGISTRY_PASSWORD
+CI_REGISTRY_USER
+CI_REPOSITORY_URL
+CI_SERVER_TLS_CA_FILE
+CI_SERVER
+CI_SHARED_ENVIRONMENT
+FF_CMD_DISABLE_DELAYED_ERROR_LEVEL_EXPANSION
+FF_USE_LEGACY_BUILDS_DIR_FOR_DOCKER
+FF_USE_LEGACY_VOLUMES_MOUNTING_ORDER
+```
+
+During development and testing of your CI configuration, consider verifying the presence
+of variables you haven't created yourself in a test job, before relying on them:
+
+```yaml
+test_job_name:
+  script: /bin/true
+  rules:
+    - if: '$CI_VARIABLE_NAME'
+```
+
 ### `config.toml` file
 
 NOTE: **Note:**