Merge branch 'ee-46806-typed-ci-variables-docs' into 'master'

Port of 46806-typed-ci-variables-docs to EE

See merge request gitlab-org/gitlab-ee!11991

doc/ci/variables/README.md

@@ -52,6 +52,33 @@ or directly in the `.gitlab-ci.yml` file and reuse them as you wish.
 That can be very powerful as it can be used for scripting without
 the need to specify the value itself.
 
+#### Variable types
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46806) in GitLab 11.11.
+
+There are two types of variables supported by GitLab:
+
+- `env_var`: the runner will create environment variable named same as the variable key and set its value to the variable value.
+- `file`: the runner will write the variable value to a temporary file and set the path to this file as the value of an environment variable named same as the variable key.
+
+#### Masked variables
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/13784) in GitLab 11.10
+
+By default, variables will be created as masked variables.
+This means that the value of the variable will be hidden in job logs,
+though it must match certain requirements to do so:
+
+- The value must be in a single line.
+- The value must not have escape characters.
+- The value must not use variables.
+- The value must not have any whitespace.
+- The value must be at least 8 characters long.
+
+If the value does not meet the requirements above, then the CI variable will fail to save.
+In order to save, either alter the value to meet the masking requirements
+or disable **Masked** for the variable.
+
 ## Getting started
 
 To get started with environment variables in the scope of GitLab
@@ -104,7 +131,10 @@ let's say you want to output `HELLO WORLD` for a `TEST` variable.
 You can either set the variable directly in the `.gitlab-ci.yml`
 file or through the UI.
 
-#### Via [`.gitlab-ci.yml`](../yaml/README.md#variables)
+#### Via `.gitlab-ci.yml`
+
+To create a new custom `env_var` variable via [`.gitlab-ci.yml`](../yaml/README.md#variables), define their variable/value pair under
+`variables`:
 
 ```yaml
 variables:
@@ -116,11 +146,13 @@ For a deeper look into them, see [`.gitlab-ci.yml` defined variables](#gitlab-ci
 #### Via the UI
 
 From the UI, navigate to your project's **Settings > CI/CD** and
-expand **Environment variables**. Create a new variable by naming
-it in the field **Input variable key**, and define its value in the
+expand **Variables**. Create a new variable by choosing its **type**, naming
+it in the field **Input variable key**, and defining its value in the
 **Input variable value** field:
 
-![CI/CD settings - new variable](img/new_custom_variable_example.png)
+![CI/CD settings - new variable](img/new_custom_variables_example.png)
+
+You'll also see the option to mask and/or protect your variables.
 
 Once you've set the variables, call them from the `.gitlab-ci.yml` file:
 
@@ -129,30 +161,14 @@ test_variable:
   stage: test
   script:
     - echo $CI_JOB_STAGE # calls a predefined variable
-    - echo $TEST # calls a custom variable
+    - echo $TEST # calls a custom variable of type `env_var`
+    - echo $GREETING # calls a custom variable of type `file` that contains the path to the temp file
+    - cat $GREETING # the temp file itself contains the variable value
 ```
 
 The output will be:
 
-![Output custom variable](img/custom_variable_output.png)
-
-### Masked Variables
-
-By default, variables will be created as masked variables.
-This means that the value of the variable will be hidden in job logs,
-though it must match certain requirements to do so:
-
-- The value must be in a single line.
-- The value must contain only letters, numbers, or underscores.
-- The value must not have escape characters, such as `\"`
-- The value must not use variables.
-- The value must not have any whitespace.
-- The value must be at least 8 characters long.
-
-The above rules are validated using the regex `/\A\w{8,}\z/`. If the value
-does not meet the requirements above, then the CI variable will fail to save.
-In order to save, either alter the value to meet the masking requirements or
-disable `Masked` for the variable.
+![Output custom variable](img/custom_variables_output.png)
 
 ### Syntax of environment variables in job scripts
 
@@ -299,7 +315,7 @@ use for storing things like passwords, SSH keys, and credentials.
 Group-level variables can be added by:
 
 1. Navigating to your group's **Settings > CI/CD** page.
-1. Inputing variable keys and values in the **Environment variables** section.
+1. Inputing variable types, keys, and values in the **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.
@@ -409,8 +425,7 @@ For instance, suppose you added a
 [custom variable `$TEST`](#creating-a-custom-environment-variable)
 as exemplified above and you want to override it in a manual pipeline.
 Navigate to your project's **CI/CD > Pipelines** and click **Run pipeline**.
-Choose the branch you want to run the pipeline for, then add a new variable
-pair through the UI:
+Choose the branch you want to run the pipeline for, then add a new variable through the UI:
 
 ![Override variable value](img/override_variable_manual_pipeline.png)