Merge branch 'master' into per-project-pipeline-iid

5 files changed, 141 insertions, 187 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 8d1d72c2a2b..7666219acb0 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -19,7 +19,7 @@ Here's some info we've gathered to get you started.
 The first steps towards your GitLab CI/CD journey.
 
 - [Getting started with GitLab CI/CD](quick_start/README.md): understand how GitLab CI/CD works.
-- GitLab CI/CD configuration file: [`.gitlab-ci.yml`](yaml/README.md) - Learn all about the ins and outs of `.gitlab-ci.yml`.
+- [GitLab CI/CD configuration file: `.gitlab-ci.yml`](yaml/README.md) - Learn all about the ins and outs of `.gitlab-ci.yml`.
 - [Pipelines and jobs](pipelines.md): configure your GitLab CI/CD pipelines to build, test, and deploy your application.
 - Runners: The [GitLab Runner](https://docs.gitlab.com/runner/) is responsible by running the jobs in your CI/CD pipeline. On GitLab.com, Shared Runners are enabled by default, so
 you don't need to set up anything to start to use them with GitLab CI/CD.
@@ -46,7 +46,9 @@ you don't need to set up anything to start to use them with GitLab CI/CD.
 ## Exploring GitLab CI/CD
 
 - [CI/CD Variables](variables/README.md) - Learn how to use variables defined in
-  your `.gitlab-ci.yml` or secured ones defined in your project's settings
+  your `.gitlab-ci.yml` or the ones defined in your project's settings
+  - [Where variables can be used](variables/where_variables_can_be_used.md) - A
+    deeper look on where and how the CI/CD variables can be used
 - **The permissions model** - Learn about the access levels a user can have for
   performing certain CI actions
   - [User permissions](../user/permissions.md#gitlab-ci)
diff --git a/doc/ci/autodeploy/index.md b/doc/ci/autodeploy/index.md
index 7102af5c529..985ec4b972c 100644
--- a/doc/ci/autodeploy/index.md
+++ b/doc/ci/autodeploy/index.md
@@ -1,129 +1 @@
-# Auto Deploy
-
-> [Introduced][mr-8135] in GitLab 8.15.
-> Auto deploy is an experimental feature and is **not recommended for Production use** at this time.
-
-> As of GitLab 9.1, access to the container registry is only available while the
-Pipeline is running. Restarting a pod, scaling a service, or other actions which
-require on-going access **will fail**. On-going secure access is planned for a
-subsequent release.
-
-> As of GitLab 10.0, Auto Deploy templates are **deprecated** and the
-functionality has been included in [Auto
-DevOps](../../topics/autodevops/index.md).
-
-Auto deploy is an easy way to configure GitLab CI for the deployment of your
-application. GitLab Community maintains a list of `.gitlab-ci.yml`
-templates for various infrastructure providers and deployment scripts
-powering them. These scripts are responsible for packaging your application,
-setting up the infrastructure and spinning up necessary services (for
-example a database).
-
-## How it works
-
-The Autodeploy templates are based on the [kubernetes-deploy][kube-deploy]
-project which is used to simplify the deployment process to Kubernetes by
-providing intelligent `build`, `deploy`, and `destroy` commands which you can
-use in your `.gitlab-ci.yml` as is. It uses [Herokuish](https://github.com/gliderlabs/herokuish),
-which uses [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks)
-to do some of the work, plus some of GitLab's own tools to package it all up. For
-your convenience, a [Docker image][kube-image] is also provided.
-
-You can use the [Kubernetes project service](../../user/project/integrations/kubernetes.md)
-to store credentials to your infrastructure provider and they will be available
-during the deployment.
-
-## Quick start
-
-We made a [simple guide](quick_start_guide.md) to using Auto Deploy with GitLab.com.
-
-For a demonstration of GitLab Auto Deploy, read the blog post [Auto Deploy from GitLab to an OpenShift Container Cluster](https://about.gitlab.com/2017/05/16/devops-containers-gitlab-openshift/)
-
-## Supported templates
-
-The list of supported auto deploy templates is available in the
-[gitlab-ci-yml project][auto-deploy-templates].
-
-## Configuration
-
->**Note:**
-In order to understand why the following steps are required, read the
-[how it works](#how-it-works) section.
-
-To configure Autodeploy, you will need to:
-
-1. Enable a deployment [project service][project-services] to store your
-   credentials. For example, if you want to deploy to OpenShift you have to
-   enable [Kubernetes service][kubernetes-service].
-1. Configure GitLab Runner to use the
-   [Docker or Kubernetes executor](https://docs.gitlab.com/runner/executors/) with
-   [privileged mode enabled][docker-in-docker].
-1. Navigate to the "Project" tab and click "Set up auto deploy" button.
-   ![Auto deploy button](img/auto_deploy_button.png)
-1. Select a template.
-  ![Dropdown with auto deploy templates](img/auto_deploy_dropdown.png)
-1. Commit your changes and create a merge request.
-1. Test your deployment configuration using a [Review App][review-app] that was
-   created automatically for you.
-
-## Private project support
-
-> Experimental support [introduced][mr-2] in GitLab 9.1.
-
-When a project has been marked as private, GitLab's [Container Registry][container-registry] requires authentication when downloading containers. Auto deploy will automatically provide the required authentication information to Kubernetes, allowing temporary access to the registry. Authentication credentials will be valid while the pipeline is running, allowing for a successful initial deployment.
-
-After the pipeline completes, Kubernetes will no longer be able to access the container registry. Restarting a pod, scaling a service, or other actions which require on-going access to the registry will fail. On-going secure access is planned for a subsequent release.
-
-## PostgreSQL database support
-
-> Experimental support [introduced][mr-8] in GitLab 9.1.
-
-In order to support applications that require a database, [PostgreSQL][postgresql] is provisioned by default. Credentials to access the database are preconfigured, but can be customized by setting the associated [variables](#postgresql-variables). These credentials can be used for defining a `DATABASE_URL` of the format: `postgres://user:password@postgres-host:postgres-port/postgres-database`. It is important to note that the database itself is temporary, and contents will be not be saved.
-
-PostgreSQL provisioning can be disabled by setting the variable `DISABLE_POSTGRES` to `"yes"`.
-
-The following PostgreSQL variables are supported:
-
-1. `DISABLE_POSTGRES: "yes"`: disable automatic deployment of PostgreSQL
-1. `POSTGRES_USER: "my-user"`: use custom username for PostgreSQL
-1. `POSTGRES_PASSWORD: "password"`: use custom password for PostgreSQL
-1. `POSTGRES_DB: "my database"`: use custom database name for PostgreSQL
-
-## Auto Monitoring
-
-> Introduced in [GitLab 9.5](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13438).
-
-Apps auto-deployed using one the [Kubernetes templates](#supported-templates) can also be automatically monitored for:
-
-* Response Metrics: latency, throughput, error rate
-* System Metrics: CPU utilization, memory utilization
-
-Metrics are gathered from [nginx-ingress](../../user/project/integrations/prometheus_library/nginx_ingress.md) and [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md).
-
-To view the metrics, open the [Monitoring dashboard for a deployed environment](../environments.md#monitoring-environments).
-
-![Auto Metrics](img/auto_monitoring.png)
-
-### Configuring Auto Monitoring
-
-If GitLab has been deployed using the [omnibus-gitlab](../../install/kubernetes/gitlab_omnibus.md) Helm chart, no configuration is required.
-
-If you have installed GitLab using a different method:
-
-1. [Deploy Prometheus](../../user/project/integrations/prometheus.md#configuring-your-own-prometheus-server-within-kubernetes) into your Kubernetes cluster
-1. If you would like response metrics, ensure you are running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](https://github.com/kubernetes/ingress/blob/master/examples/customization/custom-vts-metrics/nginx/nginx-vts-metrics-conf.yaml).
-1. Finally, [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) the NGINX Ingress deployment to be scraped by Prometheus using `prometheus.io/scrape: "true"` and `prometheus.io/port: "10254"`.
-
-[mr-8135]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8135
-[mr-2]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/2
-[mr-8]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/8
-[project-settings]: https://docs.gitlab.com/ce/public_access/public_access.html
-[project-services]: ../../user/project/integrations/project_services.md
-[auto-deploy-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml/tree/master/autodeploy
-[kubernetes-service]: ../../user/project/integrations/kubernetes.md
-[docker-in-docker]: ../docker/using_docker_build.md#use-docker-in-docker-executor
-[review-app]: ../review_apps/index.md
-[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry"
-[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project"
-[container-registry]: https://docs.gitlab.com/ce/user/project/container_registry.html
-[postgresql]: https://www.postgresql.org/
+This document was moved to [another location](../../topics/autodevops/index.md#auto-deploy).
diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 3a491f0073c..7f034409580 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -24,7 +24,7 @@ Environments are like tags for your CI jobs, describing where code gets deployed
 Deployments are created when [jobs] deploy versions of code to environments,
 so every environment can have one or more deployments. GitLab keeps track of
 your deployments, so you always know what is currently being deployed on your
-servers. If you have a deployment service such as [Kubernetes][kubernetes-service]
+servers. If you have a deployment service such as [Kubernetes][kube]
 enabled for your project, you can use it to assist with your deployments, and
 can even access a [web terminal](#web-terminals) for your environment from within GitLab!
 
@@ -246,23 +246,14 @@ As the name suggests, it is possible to create environments on the fly by just
 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 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. There are other variables that
-are unsupported in environment name context:
-- `CI_PIPELINE_ID`
-- `CI_JOB_ID`
-- `CI_JOB_TOKEN`
-- `CI_BUILD_ID`
-- `CI_BUILD_TOKEN`
-- `CI_REGISTRY_USER`
-- `CI_REGISTRY_PASSWORD`
-- `CI_REPOSITORY_URL`
-- `CI_ENVIRONMENT_URL`
-- `CI_DEPLOY_USER`
-- `CI_DEPLOY_PASSWORD`
+NOTE: **Note:**
+The `name` and `url` parameters can use most of the CI/CD variables,
+including [predefined](variables/README.md#predefined-variables-environment-variables),
+[secret](variables/README.md#secret-variables) and
+[`.gitlab-ci.yml` variables](yaml/README.md#variables). You however cannot use variables
+defined under `script` or on the Runner's side. There are also other variables that
+are unsupported in the context of `environment:name`. You can read more about
+[where variables can be used](variables/where_variables_can_be_used.md).
 
 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
@@ -605,7 +596,7 @@ Web terminals were added in GitLab 8.15 and are only available to project
 masters and owners.
 
 If you deploy to your environments with the help of a deployment service (e.g.,
-the [Kubernetes service][kubernetes-service]), GitLab can open
+the [Kubernetes integration][kube]), GitLab can open
 a terminal session to your environment! This is a very powerful feature that
 allows you to debug issues without leaving the comfort of your web browser. To
 enable it, just follow the instructions given in the service integration
@@ -671,7 +662,6 @@ Below are some links you may find interesting:
 [Pipelines]: pipelines.md
 [jobs]: yaml/README.md#jobs
 [yaml]: yaml/README.md
-[kubernetes-service]: ../user/project/integrations/kubernetes.md
 [environments]: #environments
 [deployments]: #deployments
 [permissions]: ../user/permissions.md
@@ -683,5 +673,5 @@ Below are some links you may find interesting:
 [gitlab-flow]: ../workflow/gitlab_flow.md
 [gitlab runner]: https://docs.gitlab.com/runner/
 [git-strategy]: yaml/README.md#git-strategy
-[kube]: ../user/project/integrations/kubernetes.md
+[kube]: ../user/project/clusters/index.md
 [prom]: ../user/project/integrations/prometheus.md
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index bf32f6567a5..dfea10314b9 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -22,6 +22,12 @@ For example, if you define `API_TOKEN=secure` as a secret variable and
 `API_TOKEN=yaml` in your `.gitlab-ci.yml`, the `API_TOKEN` will take the value
 `secure` as the secret variables are higher in the chain.
 
+## Unsupported variables
+
+There are cases where some variables cannot be used in the context of a
+`.gitlab-ci.yml` definition (for example under `script`). Read more
+about which variables are [not supported](where_variables_can_be_used.md).
+
 ## Predefined variables (Environment variables)
 
 Some of the predefined environment variables are available only if a minimum
@@ -36,6 +42,7 @@ future GitLab releases.**
 
 | Variable                        | GitLab | Runner | Description |
 |-------------------------------- |--------|--------|-------------|
+| **ARTIFACT_DOWNLOAD_ATTEMPTS**  | 8.15   | 1.9    | Number of attempts to download artifacts running a job |
 | **CI**                          | all    | 0.4    | Mark that job is executed in CI environment |
 | **CI_COMMIT_REF_NAME**          | 9.0    | all    | The branch or tag name for which project is built |
 | **CI_COMMIT_REF_SLUG**          | 9.0    | all    | `$CI_COMMIT_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. |
@@ -46,6 +53,8 @@ future GitLab releases.**
 | **CI_COMMIT_DESCRIPTION**       | 10.8   | all    | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. |
 | **CI_CONFIG_PATH**              | 9.4    | 0.5    | The path to CI config file. Defaults to `.gitlab-ci.yml` |
 | **CI_DEBUG_TRACE**              | all    | 1.7    | Whether [debug tracing](#debug-tracing) is enabled |
+| **CI_DEPLOY_USER**              | 10.8   | all    | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
+| **CI_DEPLOY_PASSWORD**          | 10.8   | all    | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
 | **CI_DISPOSABLE_ENVIRONMENT**   | all    | 10.1   | Marks that the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. |
 | **CI_ENVIRONMENT_NAME**         | 8.15   | all    | The name of the environment for this job |
 | **CI_ENVIRONMENT_SLUG**         | 8.15   | all    | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. |
@@ -83,16 +92,13 @@ future GitLab releases.**
 | **CI_SERVER_REVISION**          | all    | all    | GitLab revision that is used to schedule jobs |
 | **CI_SERVER_VERSION**           | all    | all    | GitLab version that is used to schedule jobs |
 | **CI_SHARED_ENVIRONMENT**       | all    | 10.1   | Marks that the job is executed in a shared environment (something that is persisted across CI invocations like `shell` or `ssh` executor). If the environment is shared, it is set to true, otherwise it is not defined at all. |
-| **ARTIFACT_DOWNLOAD_ATTEMPTS**  | 8.15   | 1.9    | Number of attempts to download artifacts running a job |
 | **GET_SOURCES_ATTEMPTS**        | 8.15   | 1.9    | Number of attempts to fetch sources running a job |
 | **GITLAB_CI**                   | all    | all    | Mark that job is executed in GitLab CI environment |
-| **GITLAB_USER_ID**              | 8.12   | all    | The id of the user who started the job |
 | **GITLAB_USER_EMAIL**           | 8.12   | all    | The email of the user who started the job |
+| **GITLAB_USER_ID**              | 8.12   | all    | The id of the user who started the job |
 | **GITLAB_USER_LOGIN**           | 10.0   | all    | The login username of the user who started the job |
 | **GITLAB_USER_NAME**            | 10.0   | all    | The real name of the user who started the job |
 | **RESTORE_CACHE_ATTEMPTS**      | 8.15   | 1.9    | Number of attempts to restore the cache running a job |
-| **CI_DEPLOY_USER**              | 10.8   | all    | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
-| **CI_DEPLOY_PASSWORD**          | 10.8   | all    | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
 
 ## 9.0 Renaming
 
@@ -216,8 +222,8 @@ are set in the build environment. These variables are only defined for
 [deployment jobs](../environments.md). Please consult the documentation of
 the project services that you are using to learn which variables they define.
 
-An example project service that defines deployment variables is
-[Kubernetes Service](../../user/project/integrations/kubernetes.md#deployment-variables).
+An example project service that defines deployment variables is the
+[Kubernetes integration](../../user/project/clusters/index.md#deployment-variables).
 
 ## Debug tracing
 
@@ -541,34 +547,6 @@ Below you can find supported syntax reference:
     Pattern matching is case-sensitive by default. Use `i` flag modifier, like
     `/pattern/i` to make a pattern case-insensitive.
 
-### 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_PIPELINE_ID`
-- `CI_JOB_ID`
-- `CI_JOB_TOKEN`
-- `CI_BUILD_ID`
-- `CI_BUILD_TOKEN`
-- `CI_REGISTRY_USER`
-- `CI_REGISTRY_PASSWORD`
-- `CI_REPOSITORY_URL`
-- `CI_ENVIRONMENT_URL`
-- `CI_DEPLOY_USER`
-- `CI_DEPLOY_PASSWORD`
-
-These variables are also not supported in a context 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"
 [envs]: ../environments.md
@@ -580,5 +558,4 @@ These variables are also not supported in a context of a
 [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
 [gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token
diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md
new file mode 100644
index 00000000000..9800784d918
--- /dev/null
+++ b/doc/ci/variables/where_variables_can_be_used.md
@@ -0,0 +1,113 @@
+# Where variables can be used
+
+As it's described in the [CI/CD variables](README.md) docs, you can
+define many different variables. Some of them can be used for all GitLab CI/CD
+features, but some of them are more or less limited.
+
+This document describes where and how the different types of variables can be used.
+
+## Variables usage
+
+There are basically two places where you can use any defined variables:
+
+1. On GitLab's side there's `.gitlab-ci.yml`
+1. On the Runner's side there's `config.toml`
+
+### `.gitlab-ci.yml` file
+
+| Definition                           | Can be expanded?  | Expansion place | Description  |
+|--------------------------------------|-------------------|-----------------|--------------|
+| `environment:url`                    | yes               | GitLab           | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<ul><li>**Supported:** all variables defined for a job (secret variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules)</li><li>**Not suported:** variables defined in Runner's `config.toml` and variables created in job's `script`</li></ul> |
+| `environment:name`                   | yes               | GitLab           | Similar to `environment:url`, but the variables expansion **doesn't support**: <ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> |
+| `variables` | yes               | Runner          | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
+| `image`          | yes               | Runner          | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
+| `services:[]` | yes           | Runner          | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
+| `services:[]:name` | yes  | Runner          | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
+| `cache:key` | yes               | Runner          | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
+| `artifacts:name`                     | yes               | Runner          | The variable expansion is made by GitLab Runner's shell environment  |
+| `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`.<br/>**Not supported:**<ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> |
+
+### `config.toml` file
+
+NOTE: **Note:**
+You can read more about `config.toml` in the [Runner's docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html).
+
+| Definition                           | Can be expanded? | Description |
+|--------------------------------------|------------------|-------------|
+| `runners.environment`                | yes              | The variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
+| `runners.kubernetes.pod_labels`      | yes              | The Variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
+| `runners.kubernetes.pod_annotations` | yes              | The Variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
+
+## Expansion mechanisms
+
+There are three expansion mechanisms:
+
+- GitLab
+- GitLab Runner
+- Execution shell environment
+
+### GitLab internal variable expansion mechanism
+
+The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`.
+Each form is handled in the same way, no matter which OS/shell will finally handle the job,
+since the expansion is done in GitLab before any Runner will get the job.
+
+### GitLab Runner internal variable expansion mechanism
+
+- **Supported:** secret variables, `.gitlab-ci.yml` variables, `config.toml` variables, and
+  variables from triggers and pipeline schedules
+- **Not supported:** variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`)
+
+The Runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle
+only variables defined as `$variable` and `${variable}`. What's also important, is that
+the expansion is done only once, so nested variables may or may not work, depending on the
+ordering of variables definitions.
+
+### Execution shell environment
+
+This is an expansion that takes place during the `script` execution.
+How it works depends on the used shell (bash/sh/cmd/PowerShell). For example, if the job's
+`script` contains a line `echo $MY_VARIABLE-${MY_VARIABLE_2}`, it should be properly handled
+by bash/sh (leaving empty strings or some values depending whether the variables were
+defined or not), but will not work with Windows' cmd/PowerShell, since these shells
+are using a different variables syntax.
+
+**Supported:**
+
+- The `script` may use all available variables that are default for the shell (e.g., `$PATH` which
+  should be present in all bash/sh shells) and all variables defined by GitLab CI/CD (secret variables,
+  `.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules).
+- The `script` may also use all variables defined in the lines before. So, for example, if you define
+  a variable `export MY_VARIABLE="test"`:
+
+  - in `before_script`, it will work in the following lines of `before_script` and
+    all lines of the related `script`
+  - in `script`, it will work in the following lines of `script`
+  - in `after_script`, it will work in following lines of `after_script`
+
+## Persisted variables
+
+NOTE: **Note:**
+Some of the persisted variables contain tokens and cannot be used by some definitions
+due to security reasons.
+
+The following variables are known as "persisted":
+
+- `CI_PIPELINE_ID`
+- `CI_JOB_ID`
+- `CI_JOB_TOKEN`
+- `CI_BUILD_ID`
+- `CI_BUILD_TOKEN`
+- `CI_REGISTRY_USER`
+- `CI_REGISTRY_PASSWORD`
+- `CI_REPOSITORY_URL`
+- `CI_DEPLOY_USER`
+- `CI_DEPLOY_PASSWORD`
+
+They are:
+
+- **supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner"
+- **not supported:**
+  - by the definitions [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "GitLab"
+  - in the `only` and `except` [variables expressions](README.md#variables-expressions)