summaryrefslogtreecommitdiff
path: root/doc/ci/variables/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ci/variables/README.md')
-rw-r--r--doc/ci/variables/README.md92
1 files changed, 64 insertions, 28 deletions
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index 6313ffc584d..1ba22070abe 100644
--- a/doc/ci/variables/README.md
+++ b/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.
@@ -350,6 +366,25 @@ Protected variables can be added by going to your project's
Once you set them, they will be available for all subsequent pipelines.
+### Limiting environment scopes of environment variables **[PREMIUM]**
+
+> [Introduced][ee-2112] in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
+
+You can limit the environment scope of a variable by
+[defining which environments][envs] it can be available for.
+
+Wildcards can be used, and the default environment scope is `*` which means
+any jobs will have this variable, not matter if an environment is defined or
+not.
+
+For example, if the environment scope is `production`, then only the jobs
+having the environment `production` defined would have this specific variable.
+Wildcards (`*`) can be used along with the environment name, therefore if the
+environment scope is `review/*` then any jobs with environment names starting
+with `review/` would have that particular variable.
+
+To learn more about about scoping environments, see [Scoping environments with specs](../environments.md#scoping-environments-with-specs-premium).
+
### Deployment environment variables
> Introduced in GitLab 8.15.
@@ -390,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)
@@ -662,13 +696,15 @@ MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw'
...
```
+[ee-2112]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2112
[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 "Simple protection of CI variables"
-[eep]: https://about.gitlab.com/pricing/ "Available only in GitLab Premium"
[envs]: ../environments.md
[protected branches]: ../../user/project/protected_branches.md
[protected tags]: ../../user/project/protected_tags.md
[shellexecutors]: https://docs.gitlab.com/runner/executors/
[triggered]: ../triggers/README.md
+[trigger-job-token]: ../triggers/README.md#ci-job-token
[gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token
[registry]: ../../user/project/container_registry.md
[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories
+[get-job-artifacts]: ../../api/jobs.html#get-job-artifacts