Commit ed68da34 authored by Krasimir Angelov's avatar Krasimir Angelov Committed by Marcia Ramos

Update docs related to CI variables

Add `Variable Types` section to explain supported variable types and
update example and related screenshots.
parent 01f2186e
......@@ -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.
......@@ -390,8 +406,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)
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment