diff options
Diffstat (limited to 'doc/ci/variables')
| -rw-r--r-- | doc/ci/variables/README.md | 92 | ||||
| -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 | |||
| -rw-r--r-- | doc/ci/variables/where_variables_can_be_used.md | 19 |
7 files changed, 83 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: - + + +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: - - -### 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. + ### 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:  @@ -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 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 diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 091ddcb0bae..0470cf52654 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -112,3 +112,22 @@ They are: - Not supported: - For definitions where the ["Expansion place"](#gitlab-ciyml-file) is GitLab. - In the `only` and `except` [variables expressions](README.md#environment-variables-expressions). + +## Variables with an environment scope + +Variables defined with an environment scope are supported. Given that +there is a variable `$STAGING_SECRET` defined in a scope of +`review/staging/*`, the following job that is using dynamic environments +is going to be created, based on the matching variable expression: + +```yaml +my-job: + stage: staging + environment: + name: review/$CI_JOB_STAGE/deploy + script: + - 'deploy staging' + only: + variables: + - $STAGING_SECRET == 'something' +``` |
