diff options
author | Krasimir Angelov <kangelov@gitlab.com> | 2019-05-03 16:18:38 +0300 |
---|---|---|
committer | Marcia Ramos <marcia@gitlab.com> | 2019-05-03 16:18:38 +0300 |
commit | ed68da34ab5c7b1ef7a1fb3fdfc1e24ee68ce1bc (patch) | |
tree | 6d1c0fe380dc2bd7f5315bb31d5f0f438f53df99 /doc/ci | |
parent | 01f2186e0bfe79d6eb8f0ce3fa8b81d5ceb47ebe (diff) |
Update docs related to CI variables
Add `Variable Types` section to explain supported variable types and
update example and related screenshots.
Diffstat (limited to 'doc/ci')
-rw-r--r-- | doc/ci/variables/README.md | 69 | ||||
-rw-r--r-- | doc/ci/variables/img/custom_variable_output.png | bin | 70552 -> 0 bytes | |||
-rw-r--r-- | doc/ci/variables/img/custom_variables_output.png | bin | 0 -> 89185 bytes | |||
-rw-r--r-- | doc/ci/variables/img/new_custom_variable_example.png | bin | 44164 -> 0 bytes | |||
-rw-r--r-- | doc/ci/variables/img/new_custom_variables_example.png | bin | 0 -> 70758 bytes | |||
-rw-r--r-- | doc/ci/variables/img/override_variable_manual_pipeline.png | bin | 29090 -> 41714 bytes |
6 files changed, 42 insertions, 27 deletions
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 6313ffc584d..ace439900ab 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. @@ -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) diff --git a/doc/ci/variables/img/custom_variable_output.png b/doc/ci/variables/img/custom_variable_output.png Binary files differdeleted file mode 100644 index 50f3bceff9a..00000000000 --- a/doc/ci/variables/img/custom_variable_output.png +++ /dev/null diff --git a/doc/ci/variables/img/custom_variables_output.png b/doc/ci/variables/img/custom_variables_output.png Binary files differnew file mode 100644 index 00000000000..29f5c63b3d9 --- /dev/null +++ b/doc/ci/variables/img/custom_variables_output.png diff --git a/doc/ci/variables/img/new_custom_variable_example.png b/doc/ci/variables/img/new_custom_variable_example.png Binary files differdeleted file mode 100644 index d169c5f1806..00000000000 --- a/doc/ci/variables/img/new_custom_variable_example.png +++ /dev/null diff --git a/doc/ci/variables/img/new_custom_variables_example.png b/doc/ci/variables/img/new_custom_variables_example.png Binary files differnew file mode 100644 index 00000000000..4b78e0ff587 --- /dev/null +++ b/doc/ci/variables/img/new_custom_variables_example.png diff --git a/doc/ci/variables/img/override_variable_manual_pipeline.png b/doc/ci/variables/img/override_variable_manual_pipeline.png Binary files differindex 3bcd354e096..3c8c59720cf 100644 --- a/doc/ci/variables/img/override_variable_manual_pipeline.png +++ b/doc/ci/variables/img/override_variable_manual_pipeline.png |