Merge branch 'docs/restore-variable-naming' into 'master'

Documentation now matches UI copy

Closes #56783

See merge request gitlab-org/gitlab-ce!24659

doc/ci/caching/index.md

@@ -29,7 +29,7 @@ needed to compile the project:
   Cache was designed to be used to speed up invocations of subsequent runs of a
   given job, by keeping things like dependencies (e.g., npm packages, Go vendor
   packages, etc.) so they don't have to be re-fetched from the public internet.
-  While the cache can be abused to pass intermediate build results between 
+  While the cache can be abused to pass intermediate build results between
   stages, there may be cases where artifacts are a better fit.
 - `artifacts`: **Use for stage results that will be passed between stages.**
   Artifacts were designed to upload some compiled/generated bits of the build,
@@ -40,10 +40,10 @@ needed to compile the project:
   comply to this rule trigger an unintuitive and illogical error message (an
   enhancement is discussed at
   [https://gitlab.com/gitlab-org/gitlab-ce/issues/15530](https://gitlab.com/gitlab-org/gitlab-ce/issues/15530)
-  ). Artifacts need to be uploaded to the GitLab instance (not only the GitLab 
-  runner) before the next stage job(s) can start, so you need to evaluate 
-  carefully whether your bandwidth allows you to profit from parallelization 
-  with stages and shared artifacts before investing time in changes to the 
+  ). Artifacts need to be uploaded to the GitLab instance (not only the GitLab
+  runner) before the next stage job(s) can start, so you need to evaluate
+  carefully whether your bandwidth allows you to profit from parallelization
+  with stages and shared artifacts before investing time in changes to the
   setup.
 
 
@@ -90,7 +90,7 @@ cache, when declaring `cache` in your jobs, use one or a mix of the following:
   that will be only available to a particular project.
 - [Use a `key`](../yaml/README.md#cache-key) that fits your workflow (e.g.,
   different caches on each branch). For that, you can take advantage of the
-  [CI/CD predefined variables](../variables/README.md#predefined-variables-environment-variables).
+  [CI/CD predefined variables](../variables/README.md#predefined-environment-variables).
 
 TIP: **Tip:**
 Using the same Runner for your pipeline, is the most simple and efficient way to

doc/ci/docker/using_kaniko.md

@@ -40,7 +40,7 @@ In the following example, kaniko is used to build a Docker image and then push
 it to [GitLab Container Registry](../../user/project/container_registry.md).
 The job will run only when a tag is pushed. A `config.json` file is created under
 `/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the
-[environment variables](../variables/README.md#predefined-variables-environment-variables)
+[environment variables](../variables/README.md#predefined-environment-variables)
 GitLab CI/CD provides. In the last step, kaniko uses the `Dockerfile` under the
 root directory of the project, builds the Docker image and pushes it to the
 project's Container Registry while tagging it with the Git tag:

doc/ci/environments.md

@@ -249,7 +249,7 @@ the basis of [Review apps](review_apps/index.md).
 
 NOTE: **Note:**
 The `name` and `url` parameters can use most of the CI/CD variables,
-including [predefined](variables/README.md#predefined-variables-environment-variables),
+including [predefined](variables/README.md#predefined-environment-variables),
 [project/group ones](variables/README.md#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

doc/ci/examples/artifactory_and_gitlab/index.md

@@ -107,7 +107,7 @@ Now it's time we set up [GitLab CI/CD](https://about.gitlab.com/features/gitlab-
 GitLab CI/CD uses a file in the root of the repo, named `.gitlab-ci.yml`, to read the definitions for jobs
 that will be executed by the configured GitLab Runners. You can read more about this file in the [GitLab Documentation](https://docs.gitlab.com/ee/ci/yaml/).
 
-First of all, remember to set up variables for your deployment. Navigate to your project's **Settings > CI/CD > Variables** page
+First of all, remember to set up variables for your deployment. Navigate to your project's **Settings > CI/CD > Environment variables** page
 and add the following ones (replace them with your current values, of course):
 
 - **MAVEN_REPO_URL**: `http://artifactory.example.com:8081/artifactory` (your Artifactory URL)

doc/ci/examples/container_scanning.md

@@ -22,7 +22,7 @@ container_scanning:
   variables:
     DOCKER_DRIVER: overlay2
     ## Define two new variables based on GitLab's CI/CD predefined variables
-    ## https://docs.gitlab.com/ee/ci/variables/#predefined-variables-environment-variables
+    ## https://docs.gitlab.com/ee/ci/variables/#predefined-environment-variables
     CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
     CI_APPLICATION_TAG: $CI_COMMIT_SHA
   allow_failure: true
@@ -87,7 +87,7 @@ container_scanning:
   variables:
     DOCKER_DRIVER: overlay2
     ## Define two new variables based on GitLab's CI/CD predefined variables
-    ## https://docs.gitlab.com/ee/ci/variables/#predefined-variables-environment-variables
+    ## https://docs.gitlab.com/ee/ci/variables/#predefined-environment-variables
     CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
     CI_APPLICATION_TAG: $CI_COMMIT_SHA
   allow_failure: true

doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md

@@ -104,7 +104,7 @@ to ensure our deployments only happen when we push to the master branch.
 
 Now, since the steps defined in `.gitlab-ci.yml` require credentials to login
 to CF, you'll need to add your CF credentials as [environment
-variables](../../variables/README.md#predefined-variables-environment-variables)
+variables](../../variables/README.md#predefined-environment-variables)
 on GitLab CI/CD. To set the environment variables, navigate to your project's
 **Settings > CI/CD** and expand **Variables**. Name the variables
 `CF_USERNAME` and `CF_PASSWORD` and set them to the correct values.

doc/ci/examples/test-and-deploy-python-application-to-heroku.md

@@ -47,7 +47,7 @@ This project has three jobs:
 
 ## Store API keys
 
-You'll need to create two variables in **Settings > CI/CD > Variables** in your GitLab project:
+You'll need to create two variables in **Settings > CI/CD > Environment variables** in your GitLab project:
 
 - `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app.
 - `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.

doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md

@@ -43,7 +43,7 @@ This project has three jobs:
 
 ## Store API keys
 
-You'll need to create two variables in your project's **Settings > CI/CD > Variables**:
+You'll need to create two variables in your project's **Settings > CI/CD > Environment variables**:
 
 - `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app.
 - `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.

doc/ci/triggers/README.md

@@ -224,5 +224,5 @@ removed with one of the future versions of GitLab. You are advised to
 [ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017
 [ee]: https://about.gitlab.com/pricing/
 [variables]: ../variables/README.md
-[predef]: ../variables/README.md#predefined-variables-environment-variables
+[predef]: ../variables/README.md#predefined-environment-variables
 [registry]: ../../user/project/container_registry.md

doc/ci/variables/README.md

@@ -4,27 +4,33 @@ table_display_block: true
 
 # GitLab CI/CD Variables
 
-When receiving a job from GitLab CI, the [Runner] prepares the build environment.
-It starts by setting a list of **predefined variables** (environment variables)
-and a list of **user-defined variables**.
+When receiving a job from GitLab CI, the [Runner](https://docs.gitlab.com/runner/) prepares the build environment.
+It starts by setting a list of:
+
+- [Predefined environment variables](#predefined-environment-variables).
+- Other variables.
 
 ## Priority of variables
 
-The variables can be overwritten and they take precedence over each other in
-this order:
+Variables of different types can take precedence over other variables, depending on where they are defined.
+
+The order of precedence for variables is (from highest to lowest):
+
+1. [Trigger variables](../triggers/README.md#pass-job-variables-to-a-trigger) or [scheduled pipeline variables](../../user/project/pipelines/schedules.md#making-use-of-scheduled-pipeline-variables).
+1. Project-level [variables](#variables) or [protected variables](#protected-variables).
+1. Group-level [variables](#variables) or [protected variables](#protected-variables).
+1. YAML-defined [job-level variables](../yaml/README.md#variables).
+1. YAML-defined [global variables](../yaml/README.md#variables).
+1. [Deployment variables](#deployment-variables).
+1. [Predefined environment variables](#predefined-environment-variables).
 
-1. [Trigger variables][triggers] or [scheduled pipeline variables](../../user/project/pipelines/schedules.md#making-use-of-scheduled-pipeline-variables) (take precedence over all)
-1. Project-level [variables](#variables) or [protected variables](#protected-variables)
-1. Group-level [variables](#variables) or [protected variables](#protected-variables)
-1. YAML-defined [job-level variables](../yaml/README.md#variables)
-1. YAML-defined [global variables](../yaml/README.md#variables)
-1. [Deployment variables](#deployment-variables)
-1. [Predefined variables](#predefined-variables-environment-variables) (are the
-   lowest in the chain)
+For example, you define:
 
-For example, if you define `API_TOKEN=secure` as a project variable and
-`API_TOKEN=yaml` in your `.gitlab-ci.yml`, the `API_TOKEN` will take the value
-`secure` as the project variables are higher in the chain.
+- `API_TOKEN=secure` as a project variable.
+- `API_TOKEN=yaml` in your `.gitlab-ci.yml`.
+
+`API_TOKEN` will take the value `secure` as the project variables take precedence over those defined
+in `.gitlab-ci.yml`.
 
 ## Unsupported variables
 
@@ -32,10 +38,10 @@ 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)
+## Predefined environment variables
 
 Some of the predefined environment variables are available only if a minimum
-version of [GitLab Runner][runner] is used. Consult the table below to find the
+version of [GitLab Runner](https://docs.gitlab.com/runner/) is used. Consult the table below to find the
 version of Runner required.
 
 NOTE: **Note:**
@@ -160,7 +166,7 @@ This feature requires GitLab Runner 0.5.0 or higher and GitLab 7.14 or higher.
 
 GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in the
 build environment. The variables are hence saved in the repository, and they
-are meant to store non-sensitive project configuration, e.g., `RAILS_ENV` or
+are meant to store non-sensitive project configuration. For example, `RAILS_ENV` or
 `DATABASE_URL`.
 
 For example, if you set the variable below globally (not inside a job), it will
@@ -208,16 +214,18 @@ GitLab CI allows you to define per-project or per-group variables
 that are set in the pipeline environment. The variables are stored out of
 the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner
 making them available during a pipeline run. It's the recommended method to
-use for storing things like passwords, SSH keys and credentials.
+use for storing things like passwords, SSH keys, and credentials.
+
+Project-level variables can be added by:
 
-Project-level variables can be added by going to your project's
-**Settings > CI/CD**, then finding the section called **Variables**.
+1. Navigating to your project's **Settings > CI/CD** page.
+1. Inputing variable keys and values in the **Environment variables** section.
 
-Likewise, group-level variables can be added by going to your group's
-**Settings > CI/CD**, then finding the section called **Variables**.
-Any variables of [subgroups] will be inherited recursively.
+Group-level variables can be added by:
 
-![Variables](img/variables.png)
+1. Navigating to your group's **Settings > CI/CD** page.
+1. Inputing variable keys and values in the **Environment variables** section. Any variables of
+   [subgroups](../../user/group/subgroups/index.md) will be inherited recursively.
 
 Once you set them, they will be available for all subsequent pipelines. You can also
 [protect your variables](#protected-variables).
@@ -621,11 +629,8 @@ Below you can find supported syntax reference:
 [envs]: ../environments.md
 [protected branches]: ../../user/project/protected_branches.md
 [protected tags]: ../../user/project/protected_tags.md
-[runner]: https://docs.gitlab.com/runner/
 [shellexecutors]: https://docs.gitlab.com/runner/executors/
 [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
 [gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token
 [registry]: ../../user/project/container_registry.md

doc/ci/yaml/README.md

@@ -1520,7 +1520,7 @@ parallel. This value has to be greater than or equal to two (2) and less than or
 This creates N instances of the same job that run in parallel. They're named
 sequentially from `job_name 1/N` to `job_name N/N`.
 
-For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.html#predefined-variables-environment-variables) are set.
+For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.html#predefined-environment-variables) are set.
 
 A simple example:
 
@@ -1977,7 +1977,7 @@ The YAML-defined variables are also set to all created service containers,
 thus allowing to fine tune them.
 
 Except for the user defined variables, there are also the ones [set up by the
-Runner itself](../variables/README.md#predefined-variables-environment-variables).
+Runner itself](../variables/README.md#predefined-environment-variables).
 One example would be `CI_COMMIT_REF_NAME` which has the value of
 the branch or tag name for which project is built. Apart from the variables
 you can set in `.gitlab-ci.yml`, there are also the so called
@@ -2027,8 +2027,8 @@ variables:
 ```
 
 NOTE: **Note:** `GIT_STRATEGY` is not supported for
-[Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html), 
-but may be in the future. See the [support Git strategy with Kubernetes executor feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/issues/3847) 
+[Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html),
+but may be in the future. See the [support Git strategy with Kubernetes executor feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/issues/3847)
 for updates.
 
 ### Git submodule strategy

doc/topics/autodevops/index.md

@@ -193,7 +193,7 @@ To add a different cluster for each environment:
    and Ingress.
 1. Make sure you have [configured your DNS](#auto-devops-base-domain) with the
    specified Auto DevOps domains.
-1. Navigate to your project's **Settings > CI/CD > Variables** and add
+1. Navigate to your project's **Settings > CI/CD > Environment variables** and add
    the `AUTO_DEVOPS_DOMAIN` variables with their respective environment
    scope.
 
@@ -693,7 +693,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac
 | `POSTGRES_ENABLED`           | Whether PostgreSQL is enabled; defaults to `"true"`. Set to `false` to disable the automatic deployment of PostgreSQL.                                                                                                        |
 | `POSTGRES_USER`              | The PostgreSQL user; defaults to `user`. Set it to use a custom username.                                                                                                                                                     |
 | `POSTGRES_PASSWORD`          | The PostgreSQL password; defaults to `testing-password`. Set it to use a custom password.                                                                                                                                     |
-| `POSTGRES_DB`                | The PostgreSQL database name; defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-variables-environment-variables). Set it to use a custom database name.                               |
+| `POSTGRES_DB`                | The PostgreSQL database name; defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-environment-variables). Set it to use a custom database name.                               |
 | `BUILDPACK_URL`              | The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`, for example `https://github.com/heroku/heroku-buildpack-ruby.git#v142` |
 | `SAST_CONFIDENCE_LEVEL`      | The minimum confidence level of security issues you want to be reported; `1` for Low, `2` for Medium, `3` for High; defaults to `3`.|
 | `DEP_SCAN_DISABLE_REMOTE_CHECKS` | Whether remote Dependency Scanning checks are disabled; defaults to `"false"`. Set to `"true"` to disable checks that send data to GitLab central servers. [Read more about remote checks](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).|

doc/topics/autodevops/quick_start_guide.md

@@ -83,7 +83,7 @@ under which this application will be deployed.
     ![GitLab GKE cluster details](img/guide_gitlab_gke_details.png)
 
 1. Once ready, click **Create Kubernetes cluster**.
- 
+
 NOTE: **Note:**
 Do not select `f1-micro` from the **Machine type** dropdown. `f1-micro` machines cannot support a full GitLab installation.
 
@@ -216,7 +216,7 @@ deployment and clicking a square will take you to the pod's logs page.
 TIP: **Tip:**
 There is only one pod hosting the application at the moment, but you can add
 more pods by defining the [`REPLICAS` variable](index.md#environment-variables)
-under **Settings > CI/CD > Variables**.
+under **Settings > CI/CD > Environment variables**.
 
 ### Working with branches
 

doc/user/project/integrations/prometheus.md

@@ -132,7 +132,7 @@ If the "No data found" screen continues to appear, it could be due to:
 [prometheus-docker-image]: https://hub.docker.com/r/prom/prometheus/
 [prometheus-yml]:samples/prometheus.yml
 [gitlab.com-ip-range]: https://gitlab.com/gitlab-com/infrastructure/issues/434
-[ci-environment-slug]: ../../../ci/variables/#predefined-variables-environment-variables
+[ci-environment-slug]: ../../../ci/variables/#predefined-environment-variables
 [ce-8935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935
 [ce-10408]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10408
 [promgldocs]: ../../../administration/monitoring/prometheus/index.md

doc/user/project/integrations/prometheus_library/index.md

@@ -29,6 +29,6 @@ In order to isolate and only display relevant metrics for a given environment,
 GitLab needs a method to detect which labels are associated. To do that,
 GitLab uses the defined queries and fills in the environment specific variables.
 Typically this involves looking for the
-[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-variables-environment-variables),
+[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-environment-variables),
 but may also include other information such as the project's Kubernetes namespace.
 Each search query is defined in the [exporter specific documentation](#exporters).

doc/user/project/integrations/prometheus_library/kubernetes.md

@@ -34,4 +34,4 @@ Prometheus needs to be deployed into the cluster and configured properly in orde
 
 In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available.
 
-Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-variables-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment.
+Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment.

doc/user/project/new_ci_build_permissions_model.md

@@ -238,6 +238,6 @@ test:
 [triggers]: ../../ci/triggers/README.md
 [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update
 [workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse
-[jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables
+[jobenv]: ../../ci/variables/README.md#predefined-environment-variables
 [2fa]: ../profile/account/two_factor_authentication.md
 [pat]: ../profile/personal_access_tokens.md