Update docs related to CI variables
Add `Variable Types` section to explain supported variable types and update example and related screenshots.
|
@ -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)
|
||||
|
||||
|
|
Before Width: | Height: | Size: 69 KiB |
BIN
doc/ci/variables/img/custom_variables_output.png
Normal file
After Width: | Height: | Size: 87 KiB |
Before Width: | Height: | Size: 43 KiB |
BIN
doc/ci/variables/img/new_custom_variables_example.png
Normal file
After Width: | Height: | Size: 69 KiB |
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 41 KiB |
Before Width: | Height: | Size: 5.2 KiB After Width: | Height: | Size: 17 KiB |
Before Width: | Height: | Size: 23 KiB After Width: | Height: | Size: 61 KiB |