Cleanup CI variables table and add a deprecation note

[ci skip]

2 files changed, 62 insertions, 65 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index cbab7c9f18d..d8fba5d7a77 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -27,6 +27,8 @@
 
 ## Breaking changes
 
+- [CI variables renaming](variables/README.md#9-0-renaming) Read about the
+  deprecated CI variables and what you should use for GitLab 9.0+.
 - [New CI job permissions model](../user/project/new_ci_build_permissions_model.md)
   Read about what changed in GitLab 8.12 and how that affects your jobs.
   There's a new way to access your Git submodules and LFS objects in jobs.
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index 4c3e7c4e86e..45304d0343f 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -27,58 +27,53 @@ 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 Runner required.
 
-| Variable                | GitLab | Runner | Description |
-|-------------------------|--------|--------|-------------|
-| **CI**                  | all    | 0.4    | Mark that job is executed in CI environment |
-| **GITLAB_CI**           | all    | all    | Mark that job is executed in GitLab CI environment |
-| **CI_SERVER**           | all    | all    | Mark that job is executed in CI environment |
-| **CI_SERVER_NAME**      | all    | all    | The name of CI server that is used to coordinate jobs |
-| **CI_SERVER_VERSION**   | all    | all    | GitLab version that is used to schedule jobs |
-| **CI_SERVER_REVISION**  | all    | all    | GitLab revision that is used to schedule jobs |
-| **CI_BUILD_ID**         | all    | all    | The unique id of the current job that GitLab CI uses internally. Deprecated, use CI_JOB_ID |
-| **CI_JOB_ID**           | 9.0    | all    | The unique id of the current job that GitLab CI uses internally |
-| **CI_BUILD_REF**        | all    | all    | The commit revision for which project is built. Deprecated, use CI_COMMIT_REF |
-| **CI_COMMIT_SHA**       | 9.0    | all    | The commit revision for which project is built |
-| **CI_BUILD_TAG**        | all    | 0.5    | The commit tag name. Present only when building tags. Deprecated, use CI_COMMIT_TAG |
-| **CI_COMMIT_TAG**       | 9.0    | 0.5    | The commit tag name. Present only when building tags. |
-| **CI_BUILD_NAME**       | all    | 0.5    | The name of the job as defined in `.gitlab-ci.yml`. Deprecated, use CI_JOB_NAME |
-| **CI_JOB_NAME**         | 9.0    | 0.5    | The name of the job as defined in `.gitlab-ci.yml` |
-| **CI_BUILD_STAGE**      | all    | 0.5    | The name of the stage as defined in `.gitlab-ci.yml`. Deprecated, use CI_JOB_STAGE |
-| **CI_JOB_STAGE**        | 9.0    | 0.5    | The name of the stage as defined in `.gitlab-ci.yml` |
-| **CI_BUILD_REF_NAME**   | all    | all    | The branch or tag name for which project is built. Deprecated, use CI_COMMIT_REF_NAME |
-| **CI_COMMIT_REF_NAME**  | 9.0    | all    | The branch or tag name for which project is built |
-| **CI_BUILD_REF_SLUG**   | 8.15   | all    | `$CI_COMMIT_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. Deprecated, use CI_COMMIT_REF_SLUG |
-| **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 `-`. Use in URLs and domain names. |
-| **CI_BUILD_REPO**       | all    | all    | The URL to clone the Git repository. Deprecated, use CI_REPOSITORY |
-| **CI_REPOSITORY_URL**   | 9.0    | all    | The URL to clone the Git repository |
-| **CI_BUILD_TRIGGERED**  | all    | 0.5    | The flag to indicate that job was [triggered]. Deprecated, use CI_PIPELINE_TRIGGERED |
-| **CI_PIPELINE_TRIGGERED** | all  | all    | The flag to indicate that job was [triggered] |
-| **CI_BUILD_MANUAL**     | 8.12   | all    | The flag to indicate that job was manually started. Deprecated, use CI_JOB_MANUAL |
-| **CI_JOB_MANUAL**       | 8.12   | all    | The flag to indicate that job was manually started |
-| **CI_BUILD_TOKEN**      | all    | 1.2    | Token used for authenticating with the GitLab Container Registry. Deprecated, use CI_JOB_TOKEN |
-| **CI_JOB_TOKEN**        | 9.0    | 1.2    | Token used for authenticating with the GitLab Container Registry |
-| **CI_PIPELINE_ID**      | 8.10   | 0.5    | The unique id of the current pipeline that GitLab CI uses internally |
-| **CI_PROJECT_ID**       | all    | all    | The unique id of the current project that GitLab CI uses internally |
-| **CI_PROJECT_NAME**     | 8.10   | 0.5    | The project name that is currently being built |
-| **CI_PROJECT_NAMESPACE**| 8.10   | 0.5    | The project namespace (username or groupname) that is currently being built |
-| **CI_PROJECT_PATH**     | 8.10   | 0.5    | The namespace with project name |
-| **CI_PROJECT_URL**      | 8.10   | 0.5    | The HTTP address to access project |
-| **CI_PROJECT_DIR**      | all    | all    | The full path where the repository is cloned and where the job is run |
-| **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. |
-| **CI_REGISTRY**         | 8.10   | 0.5    | If the Container Registry is enabled it returns the address of GitLab's Container Registry |
-| **CI_REGISTRY_IMAGE**   | 8.10   | 0.5    | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project |
-| **CI_RUNNER_ID**        | 8.10   | 0.5    | The unique id of runner being used |
-| **CI_RUNNER_DESCRIPTION** | 8.10 | 0.5    | The description of the runner as saved in GitLab |
-| **CI_RUNNER_TAGS**      | 8.10   | 0.5    | The defined runner tags |
-| **CI_DEBUG_TRACE**      | all    | 1.7    | Whether [debug tracing](#debug-tracing) is enabled |
-| **GET_SOURCES_ATTEMPTS** | 8.15    | 1.9    | Number of attempts to fetch sources running a job |
-| **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15    | 1.9    | Number of attempts to download artifacts running a job |
-| **RESTORE_CACHE_ATTEMPTS** | 8.15    | 1.9    | Number of attempts to restore the cache running a job |
-| **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 |
-| **CI_REGISTRY_USER**    | 9.0    | all    | The username to use to push containers to the GitLab Container Registry |
-| **CI_REGISTRY_PASSWORD** | 9.0   | all    | The password to use to push containers to the GitLab Container Registry |
+>**Note:**
+Starting with GitLab 9.0, we have deprecated some variables. Read the
+[9.0 Renaming](#9-0-renaming) section to find out their replacements. **You are
+strongly advised to use the new variables as we will remove the old ones in
+future GitLab releases.**
+
+| Variable                        | GitLab | Runner | Description |
+|-------------------------------- |--------|--------|-------------|
+| **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 `-`. Use in URLs and domain names. |
+| **CI_COMMIT_SHA**               | 9.0    | all    | The commit revision for which project is built |
+| **CI_COMMIT_TAG**               | 9.0    | 0.5    | The commit tag name. Present only when building tags. |
+| **CI_DEBUG_TRACE**              | all    | 1.7    | Whether [debug tracing](#debug-tracing) is enabled |
+| **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. |
+| **CI_JOB_ID**                   | 9.0    | all    | The unique id of the current job that GitLab CI uses internally |
+| **CI_JOB_MANUAL**               | 8.12   | all    | The flag to indicate that job was manually started |
+| **CI_JOB_NAME**                 | 9.0    | 0.5    | The name of the job as defined in `.gitlab-ci.yml` |
+| **CI_JOB_STAGE**                | 9.0    | 0.5    | The name of the stage as defined in `.gitlab-ci.yml` |
+| **CI_JOB_TOKEN**                | 9.0    | 1.2    | Token used for authenticating with the GitLab Container Registry |
+| **CI_REPOSITORY_URL**           | 9.0    | all    | The URL to clone the Git repository |
+| **CI_RUNNER_DESCRIPTION**       | 8.10   | 0.5    | The description of the runner as saved in GitLab |
+| **CI_RUNNER_ID**                | 8.10   | 0.5    | The unique id of runner being used |
+| **CI_RUNNER_TAGS**              | 8.10   | 0.5    | The defined runner tags |
+| **CI_PIPELINE_ID**              | 8.10   | 0.5    | The unique id of the current pipeline that GitLab CI uses internally |
+| **CI_PIPELINE_TRIGGERED**       | all    | all    | The flag to indicate that job was [triggered] |
+| **CI_PROJECT_DIR**              | all    | all    | The full path where the repository is cloned and where the job is run |
+| **CI_PROJECT_ID**               | all    | all    | The unique id of the current project that GitLab CI uses internally |
+| **CI_PROJECT_NAME**             | 8.10   | 0.5    | The project name that is currently being built |
+| **CI_PROJECT_NAMESPACE**        | 8.10   | 0.5    | The project namespace (username or groupname) that is currently being built |
+| **CI_PROJECT_PATH**             | 8.10   | 0.5    | The namespace with project name |
+| **CI_PROJECT_URL**              | 8.10   | 0.5    | The HTTP address to access project |
+| **CI_REGISTRY**                 | 8.10   | 0.5    | If the Container Registry is enabled it returns the address of GitLab's Container Registry |
+| **CI_REGISTRY_IMAGE**           | 8.10   | 0.5    | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project |
+| **CI_REGISTRY_PASSWORD**        | 9.0    | all    | The password to use to push containers to the GitLab Container Registry |
+| **CI_REGISTRY_USER**            | 9.0    | all    | The username to use to push containers to the GitLab Container Registry |
+| **CI_SERVER**                   | all    | all    | Mark that job is executed in CI environment |
+| **CI_SERVER_NAME**              | all    | all    | The name of CI server that is used to coordinate jobs |
+| **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 |
+| **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 |
+| **RESTORE_CACHE_ATTEMPTS**      | 8.15   | 1.9    | Number of attempts to restore the cache running a job |
 
 Example values:
 
@@ -121,19 +116,19 @@ To follow conventions of naming across GitLab, and to futher move away from the
 `build` term and toward `job` CI variables have been renamed for the 9.0
 release.
 
-| 8.X name | 9.0 name |
-|----------|----------|
-| CI_BUILD_ID | CI_JOB_ID |
-| CI_BUILD_REF | CI_COMMIT_SHA |
-| CI_BUILD_TAG | CI_COMMIT_TAG |
-| CI_BUILD_REF_NAME | CI_COMMIT_REF_NAME |
-| CI_BUILD_REF_SLUG | CI_COMMIT_REF_SLUG |
-| CI_BUILD_NAME | CI_JOB_NAME |
-| CI_BUILD_STAGE | CI_JOB_STAGE |
-| CI_BUILD_REPO | CI_REPOSITORY |
-| CI_BUILD_TRIGGERED | CI_PIPELINE_TRIGGERED |
-| CI_BUILD_MANUAL | CI_JOB_MANUAL |
-| CI_BUILD_TOKEN | CI_JOB_TOKEN |
+| 8.x name              | 9.0+ name               |
+| --------------------- |------------------------ |
+| `CI_BUILD_ID`         | `CI_JOB_ID`             |
+| `CI_BUILD_REF`        | `CI_COMMIT_SHA`         |
+| `CI_BUILD_TAG`        | `CI_COMMIT_TAG`         |
+| `CI_BUILD_REF_NAME`   | `CI_COMMIT_REF_NAME`    |
+| `CI_BUILD_REF_SLUG`   | `CI_COMMIT_REF_SLUG`    |
+| `CI_BUILD_NAME`       | `CI_JOB_NAME`           |
+| `CI_BUILD_STAGE`      | `CI_JOB_STAGE`          |
+| `CI_BUILD_REPO`       | `CI_REPOSITORY`         |
+| `CI_BUILD_TRIGGERED`  | `CI_PIPELINE_TRIGGERED` |
+| `CI_BUILD_MANUAL`     | `CI_JOB_MANUAL`         |
+| `CI_BUILD_TOKEN`      | `CI_JOB_TOKEN`          |
 
 ## `.gitlab-ci.yaml` defined variables