diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index e55a92dbb71fbfe551f1a893c5f3bdfe8a6ae100..234dc530db070ed19476e8ad3262d8708fb5d4df 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -86,6 +86,11 @@ 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.
 
+>**Note:**
+Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are
+strongly advised to use the new variables as we will remove the old ones in
+future GitLab releases.**
+
 | 8.x name              | 9.0+ name               |
 | --------------------- |------------------------ |
 | `CI_BUILD_ID`         | `CI_JOB_ID`             |