# Where variables can be used

> 原文：[https://docs.gitlab.com/ee/ci/variables/where_variables_can_be_used.html](https://docs.gitlab.com/ee/ci/variables/where_variables_can_be_used.html)

*   [Variables usage](#variables-usage)
    *   [`.gitlab-ci.yml` file](#gitlab-ciyml-file)
    *   [`config.toml` file](#configtoml-file)
*   [Expansion mechanisms](#expansion-mechanisms)
    *   [GitLab internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism)
    *   [GitLab Runner internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism)
    *   [Execution shell environment](#execution-shell-environment)
*   [Persisted variables](#persisted-variables)
*   [Variables with an environment scope](#variables-with-an-environment-scope)

# Where variables can be used[](#where-variables-can-be-used "Permalink")

如[CI / CD 变量](README.html)文档中所述，您可以定义许多不同的变量. 其中一些可用于所有 GitLab CI / CD 功能，但其中某些功能或多或少受到限制.

本文档描述了在何处以及如何使用不同类型的变量.

## Variables usage[](#variables-usage "Permalink")

有两个地方可以使用定义的变量. 在：

1.  GitLab 端，位于`.gitlab-ci.yml` .
2.  跑步者方面，位于`config.toml` .

### `.gitlab-ci.yml` file[](#gitlab-ciyml-file "Permalink")

| Definition | 可以扩大吗？ | 扩展地点 | Description |
| --- | --- | --- | --- |
| `environment:url` | yes | GitLab | 变量扩展由 GitLab 的[内部变量扩展机制完成](#gitlab-internal-variable-expansion-mechanism) .

支持为作业定义的所有变量（项目/组变量， `.gitlab-ci.yml`中的变量，触发器中的变量，管道计划中的变量）.

不支持在 Runner 的`config.toml`定义的变量和在 job 的`script`创建的变量. |
| `environment:name` | yes | GitLab | 与`environment:url`相似，但是变量扩展不支持以下内容：

-基于环境名称的变量（ `CI_ENVIRONMENT_NAME` ， `CI_ENVIRONMENT_SLUG` ）.
-与环境相关的任何其他变量（当前仅`CI_ENVIRONMENT_URL` ）.
- [持久变量](#persisted-variables) . |
| `resource_group` | yes | GitLab | 与`environment:url`相似，但是变量扩展不支持以下内容：

-基于环境名称的变量（ `CI_ENVIRONMENT_NAME` ， `CI_ENVIRONMENT_SLUG` ）.
-与环境相关的任何其他变量（当前仅`CI_ENVIRONMENT_URL` ）.
- [持久变量](#persisted-variables) . |
| `variables` | yes | Runner | 变量扩展由 GitLab Runner 的[内部变量扩展机制完成](#gitlab-runner-internal-variable-expansion-mechanism) |
| `image` | yes | Runner | 变量扩展由 GitLab Runner 的[内部变量扩展机制完成](#gitlab-runner-internal-variable-expansion-mechanism) |
| `services:[]` | yes | Runner | 变量扩展由 GitLab Runner 的[内部变量扩展机制完成](#gitlab-runner-internal-variable-expansion-mechanism) |
| `services:[]:name` | yes | Runner | 变量扩展由 GitLab Runner 的[内部变量扩展机制完成](#gitlab-runner-internal-variable-expansion-mechanism) |
| `cache:key` | yes | Runner | 变量扩展由 GitLab Runner 的[内部变量扩展机制完成](#gitlab-runner-internal-variable-expansion-mechanism) |
| `artifacts:name` | yes | Runner | 变量扩展由 GitLab Runner 的外壳环境完成 |
| `script`, `before_script`, `after_script` | yes | 脚本执行外壳 | 变量扩展由[执行外壳环境进行](#execution-shell-environment) |
| `only:variables:[]`, `except:variables:[]` | no | n/a | 变量必须采用`$variable`的形式. 以下不支持：

-基于环境名称的变量（ `CI_ENVIRONMENT_NAME` ， `CI_ENVIRONMENT_SLUG` ）.
-与环境相关的任何其他变量（当前仅`CI_ENVIRONMENT_URL` ）.
- [持久变量](#persisted-variables) . |

### `config.toml` file[](#configtoml-file "Permalink")

**注意：**您可以在[Runner 的 docs 中](https://docs.gitlab.com/runner/configuration/advanced-configuration.html)阅读有关`config.toml`更多信息.

| Definition | 可以扩大吗？ | Description |
| --- | --- | --- |
| `runners.environment` | yes | 变量扩展由 Runner 的[内部变量扩展机制完成](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.kubernetes.pod_labels` | yes | 变量扩展由 Runner 的[内部变量扩展机制完成](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.kubernetes.pod_annotations` | yes | 变量扩展由 Runner 的[内部变量扩展机制完成](#gitlab-runner-internal-variable-expansion-mechanism) |

## Expansion mechanisms[](#expansion-mechanisms "Permalink")

共有三种扩展机制：

*   GitLab
*   亚搏体育 app Runner
*   执行外壳环境

### GitLab internal variable expansion mechanism[](#gitlab-internal-variable-expansion-mechanism "Permalink")

扩展部分需要采用`$variable`或`${variable}`或`%variable%` . 每种格式都以相同的方式处理，无论最终由哪个 OS / shell 处理，因为扩展是在任何 Runner 获得该工作之前在 GitLab 中完成的.

### GitLab Runner internal variable expansion mechanism[](#gitlab-runner-internal-variable-expansion-mechanism "Permalink")

*   支持：项目/组变量， `.gitlab-ci.yml`变量， `config.toml`变量以及触发器，管道计划和手动管道中的变量.
*   不支持：在脚本内部定义的变量（例如， `export MY_VARIABLE="test"` ）.

跑步者使用 Go 的`os.Expand()`方法进行变量扩展. 这意味着它将仅处理定义为`$variable`和`${variable}` . 同样重要的是，扩展只能执行一次，因此嵌套变量可能会或可能不会起作用，这取决于变量定义的顺序.

### Execution shell environment[](#execution-shell-environment "Permalink")

这是`script`执行期间发生的扩展. 它的工作方式取决于所使用的 shell（ `bash` ， `sh` ， `cmd` ，PowerShell）. 例如，如果作业的`script`包含行`echo $MY_VARIABLE-${MY_VARIABLE_2}` ，则应由 bash / sh 正确处理（保留空字符串或某些值，具体取决于是否定义了变量），但不适用于 Windows 的`cmd`或 PowerShell，因为这些外壳使用不同的变量语法.

Supported:

*   该`script`可以使用外壳默认的所有可用变量（例如，应在所有 bash / sh 外壳中包含的`$PATH` ）以及 GitLab CI / CD 定义的所有变量（项目/组变量， `.gitlab-ci.yml`变量， `config.toml`变量以及触发器和管道计划中的变量）.
*   该`script`还可以使用前面各行中定义的所有变量. 因此，例如，如果您定义变量`export MY_VARIABLE="test"` ：
    *   在`before_script` ，这将在以下几行工作`before_script`和相关的所有行`script` .
    *   在`script` ，它将在以下`script`行中工作.
    *   在`after_script` ，它将在`after_script`以下行中`after_script` .

对于`after_script`脚本，它们可以：

*   仅在同一`after_script`部分中使用在脚本之前定义的变量.
*   不要使用在`before_script`和`script`定义的变量.

这些限制是因为`after_script`脚本在[单独的 shell 上下文](../yaml/README.html#before_script-and-after_script)中执行.

## Persisted variables[](#persisted-variables "Permalink")

**注意：**一些持久变量包含令牌，由于安全原因，某些定义不能使用它们.

以下变量称为"持久"：

*   `CI_PIPELINE_ID`
*   `CI_JOB_ID`
*   `CI_JOB_TOKEN`
*   `CI_BUILD_ID`
*   `CI_BUILD_TOKEN`
*   `CI_REGISTRY_USER`
*   `CI_REGISTRY_PASSWORD`
*   `CI_REPOSITORY_URL`
*   `CI_DEPLOY_USER`
*   `CI_DEPLOY_PASSWORD`

他们是：

*   支持["扩展位置"](#gitlab-ciyml-file)为的定义：
    *   赛跑者.
    *   脚本执行外壳.
*   不支持：
    *   对于["扩展位置"](#gitlab-ciyml-file)是 GitLab 的定义.
    *   在`only`和`except` [变量表达式中](README.html#environment-variables-expressions) .

## Variables with an environment scope[](#variables-with-an-environment-scope "Permalink")

支持使用环境范围定义的变量. 鉴于在`review/staging/*`范围内定义了一个变量`$STAGING_SECRET` ，将基于匹配的变量表达式创建以下使用动态环境的作业：

```
my-job:
  stage: staging
  environment:
    name: review/$CI_JOB_STAGE/deploy
  script:
    - 'deploy  staging'
  only:
    variables:
      - $STAGING_SECRET == 'something' 
```