Add docs for protected variables

1 files changed, 20 insertions, 3 deletions

diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index 0d4d08106f8..2f2023c02ae 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -11,6 +11,7 @@ this order:
 
 1. [Trigger variables][triggers] (take precedence over all)
 1. [Secret variables](#secret-variables)
+1. [Protected variables](#protected-variables)
 1. YAML-defined [job-level variables](../yaml/README.md#job-variables)
 1. YAML-defined [global variables](../yaml/README.md#variables)
 1. [Deployment variables](#deployment-variables)
@@ -153,9 +154,26 @@ storing things like passwords, secret keys and credentials.
 
 Secret variables can be added by going to your project's
 **Settings ➔ Pipelines**, then finding the section called
-**Secret Variables**.
+**Secret and protected variables**.
 
-Once you set them, they will be available for all subsequent jobs.
+Once you set them, they will be available for all subsequent pipelines.
+
+## Protected variables
+
+>**Notes:**
+- This feature requires GitLab Runner 0.4.0 or higher.
+- A protected variable is a secret variable which is protected.
+
+All secret variables could be protected. Whenever a secret variable is
+protected, it would only be securely passed to pipelines running on the
+protected branches or protected tags. The other pipelines would not get any
+protected variables.
+
+Protected variables can be added by going to your project's
+**Settings ➔ Pipelines**, then finding the section called
+**Secret and protected variables**, and check *Protected*.
+
+Once you set them, they will be available for all subsequent pipelines.
 
 ## Deployment variables
 
@@ -381,7 +399,6 @@ export CI_REGISTRY_USER="gitlab-ci-token"
 export CI_REGISTRY_PASSWORD="longalfanumstring"
 ```
 
-[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784
 [runner]: https://docs.gitlab.com/runner/
 [triggered]: ../triggers/README.md
 [triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger