debian-mirror-gitlab/doc/ci/variables/where_variables_can_be_used.md

199 lines
15 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
2020-06-23 00:09:42 +05:30
stage: Verify
2021-09-04 01:27:46 +05:30
group: Pipeline Authoring
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2019-09-04 21:01:54 +05:30
type: reference
---
2018-11-08 19:23:39 +05:30
# Where variables can be used
2021-09-30 23:02:18 +05:30
As it's described in the [CI/CD variables](index.md) docs, you can
2018-11-08 19:23:39 +05:30
define many different variables. Some of them can be used for all GitLab CI/CD
features, but some of them are more or less limited.
This document describes where and how the different types of variables can be used.
## Variables usage
2018-11-20 20:47:30 +05:30
There are two places defined variables can be used. On the:
2018-11-08 19:23:39 +05:30
2018-11-20 20:47:30 +05:30
1. GitLab side, in `.gitlab-ci.yml`.
2020-11-24 15:15:51 +05:30
1. The GitLab Runner side, in `config.toml`.
2018-11-08 19:23:39 +05:30
### `.gitlab-ci.yml` file
2019-07-07 11:18:12 +05:30
| Definition | Can be expanded? | Expansion place | Description |
|:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2021-02-22 17:27:13 +05:30
| `environment:url` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. |
2019-07-07 11:18:12 +05:30
| `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). |
2020-03-13 15:44:24 +05:30
| `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). |
2021-03-08 18:12:59 +05:30
| `include` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. <br/><br/>Predefined project variables are supported: `GITLAB_FEATURES`, `CI_DEFAULT_BRANCH`, and all variables that start with `CI_PROJECT_` (for example `CI_PROJECT_NAME`). |
2021-04-29 21:17:54 +05:30
| `variables` | yes | GitLab/Runner | The variable expansion is first made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab, and then any unrecognized or unavailable variables are expanded by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). |
2019-07-07 11:18:12 +05:30
| `image` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `services:[]` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `services:[]:name` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `cache:key` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `artifacts:name` | yes | Runner | The variable expansion is made by GitLab Runner's shell environment |
| `script`, `before_script`, `after_script` | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment) |
2021-09-04 01:27:46 +05:30
| `only:variables:[]`, `except:variables:[]`, `rules:if` | no | n/a | The variable must be in the form of `$variable`. Not supported are the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). |
2018-11-08 19:23:39 +05:30
### `config.toml` file
2019-07-07 11:18:12 +05:30
| Definition | Can be expanded? | Description |
|:-------------------------------------|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------|
2020-11-24 15:15:51 +05:30
| `runners.environment` | yes | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.kubernetes.pod_labels` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.kubernetes.pod_annotations` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
2018-11-08 19:23:39 +05:30
2021-01-03 14:25:43 +05:30
You can read more about `config.toml` in the [GitLab Runner docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html).
2018-11-08 19:23:39 +05:30
## Expansion mechanisms
There are three expansion mechanisms:
- GitLab
- GitLab Runner
- Execution shell environment
### GitLab internal variable expansion mechanism
The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`.
2021-02-22 17:27:13 +05:30
Each form is handled in the same way, no matter which OS/shell handles the job,
because the expansion is done in GitLab before any runner gets the job.
2018-11-08 19:23:39 +05:30
2021-04-29 21:17:54 +05:30
#### Nested variable expansion
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48627) in GitLab 13.10.
> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
> - It can be enabled or disabled for a single project.
> - It's disabled on GitLab.com.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-nested-variable-expansion-feature). **(FREE SELF)**
GitLab expands job variable values recursively before sending them to the runner. For example:
```yaml
- BUILD_ROOT_DIR: '${CI_BUILDS_DIR}'
- OUT_PATH: '${BUILD_ROOT_DIR}/out'
- PACKAGE_PATH: '${OUT_PATH}/pkg'
```
If nested variable expansion is:
- **Disabled**: the runner receives `${BUILD_ROOT_DIR}/out/pkg`. This is not a valid path.
- **Enabled**: the runner receives a valid, fully-formed path. For example, if `${CI_BUILDS_DIR}` is `/output`, then `PACKAGE_PATH` would be `/output/out/pkg`.
References to unavailable variables are left intact. In this case, the runner
[attempts to expand the variable value](#gitlab-runner-internal-variable-expansion-mechanism) at runtime.
For example, a variable like `CI_BUILDS_DIR` is known by the runner only at runtime.
##### Enabling the nested variable expansion feature **(FREE SELF)**
This feature comes with the `:variable_inside_variable` feature flag disabled by default.
To enable this feature, ask a GitLab administrator with [Rails console access](../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the
following command:
```ruby
# For the instance
Feature.enable(:variable_inside_variable)
# For a single project
Feature.enable(:variable_inside_variable, Project.find(<project id>))
```
To disable it:
```ruby
# For the instance
Feature.disable(:variable_inside_variable)
# For a single project
Feature.disable(:variable_inside_variable, Project.find(<project id>))
```
2018-11-08 19:23:39 +05:30
### GitLab Runner internal variable expansion mechanism
2018-12-05 23:21:45 +05:30
- Supported: project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and
2018-11-20 20:47:30 +05:30
variables from triggers, pipeline schedules, and manual pipelines.
2021-10-27 15:23:28 +05:30
- Not supported: variables defined inside of scripts (for example, `export MY_VARIABLE="test"`).
2018-11-08 19:23:39 +05:30
2021-02-22 17:27:13 +05:30
The runner uses Go's `os.Expand()` method for variable expansion. It means that it handles
2018-11-08 19:23:39 +05:30
only variables defined as `$variable` and `${variable}`. What's also important, is that
the expansion is done only once, so nested variables may or may not work, depending on the
2021-04-29 21:17:54 +05:30
ordering of variables definitions, and whether [nested variable expansion](#nested-variable-expansion)
is enabled in GitLab.
2018-11-08 19:23:39 +05:30
### Execution shell environment
2021-04-29 21:17:54 +05:30
This is an expansion phase that takes place during the `script` execution.
Its behavior depends on the shell used (`bash`, `sh`, `cmd`, PowerShell). For example, if the job's
2018-11-08 19:23:39 +05:30
`script` contains a line `echo $MY_VARIABLE-${MY_VARIABLE_2}`, it should be properly handled
by bash/sh (leaving empty strings or some values depending whether the variables were
2021-02-22 17:27:13 +05:30
defined or not), but don't work with Windows' `cmd` or PowerShell, since these shells
2021-04-29 21:17:54 +05:30
use a different variables syntax.
2018-11-08 19:23:39 +05:30
2018-12-05 23:21:45 +05:30
Supported:
2018-11-08 19:23:39 +05:30
2021-10-27 15:23:28 +05:30
- The `script` may use all available variables that are default for the shell (for example, `$PATH` which
2018-11-08 19:23:39 +05:30
should be present in all bash/sh shells) and all variables defined by GitLab CI/CD (project/group variables,
`.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules).
- The `script` may also use all variables defined in the lines before. So, for example, if you define
a variable `export MY_VARIABLE="test"`:
2021-04-29 21:17:54 +05:30
- In `before_script`, it works in the subsequent lines of `before_script` and
2018-11-20 20:47:30 +05:30
all lines of the related `script`.
2021-04-29 21:17:54 +05:30
- In `script`, it works in the subsequent lines of `script`.
- In `after_script`, it works in subsequent lines of `after_script`.
2018-11-08 19:23:39 +05:30
2019-09-04 21:01:54 +05:30
In the case of `after_script` scripts, they can:
- Only use variables defined before the script within the same `after_script`
section.
- Not use variables defined in `before_script` and `script`.
2021-04-29 21:17:54 +05:30
These restrictions exist because `after_script` scripts are executed in a
2021-09-30 23:02:18 +05:30
[separated shell context](../yaml/index.md#after_script).
2019-09-04 21:01:54 +05:30
2018-11-08 19:23:39 +05:30
## Persisted variables
The following variables are known as "persisted":
- `CI_PIPELINE_ID`
- `CI_JOB_ID`
- `CI_JOB_TOKEN`
2021-04-17 20:07:23 +05:30
- `CI_JOB_STARTED_AT`
2018-11-08 19:23:39 +05:30
- `CI_BUILD_ID`
- `CI_BUILD_TOKEN`
- `CI_REGISTRY_USER`
- `CI_REGISTRY_PASSWORD`
- `CI_REPOSITORY_URL`
- `CI_DEPLOY_USER`
- `CI_DEPLOY_PASSWORD`
They are:
2019-07-07 11:18:12 +05:30
- Supported for definitions where the ["Expansion place"](#gitlab-ciyml-file) is:
2018-12-05 23:21:45 +05:30
- Runner.
- Script execution shell.
- Not supported:
2019-07-07 11:18:12 +05:30
- For definitions where the ["Expansion place"](#gitlab-ciyml-file) is GitLab.
2021-10-27 15:23:28 +05:30
- In the `only`, `except`, and `rules` [variables expressions](../jobs/job_control.md#cicd-variable-expressions).
2019-07-31 22:56:46 +05:30
2021-01-03 14:25:43 +05:30
Some of the persisted variables contain tokens and cannot be used by some definitions
due to security reasons.
2019-07-31 22:56:46 +05:30
## 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
2021-02-22 17:27:13 +05:30
is created, based on the matching variable expression:
2019-07-31 22:56:46 +05:30
```yaml
my-job:
stage: staging
environment:
name: review/$CI_JOB_STAGE/deploy
script:
- 'deploy staging'
2021-09-04 01:27:46 +05:30
rules:
- if: $STAGING_SECRET == 'something'
2019-07-31 22:56:46 +05:30
```