Help us learn about your current experience with the documentation. Take the survey.

变量的使用场景

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

正如 CI/CD 变量 文档所述，您可以定义多种变量。其中部分变量可用于所有 GitLab CI/CD 功能，但部分变量的使用场景存在一定限制。

本文档说明不同类型变量的使用场景和方式。

变量使用场景

已定义的变量可在以下两个位置使用：

  1. GitLab 端：在 .gitlab-ci.yml 文件中
  2. GitLab Runner 端：在 config.toml 文件中

.gitlab-ci.yml 文件

定义项 是否可扩展？ 扩展位置 说明
after_script 是 脚本执行环境 变量扩展由 脚本执行环境 执行。
artifacts:name 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
artifacts:paths 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
artifacts:exclude 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
before_script 是 脚本执行环境 变量扩展由 脚本执行环境 执行。
cache:key 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
cache:paths 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
cache:policy 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
environment:name 是 GitLab 类似 environment:url，但变量扩展不支持：

- CI_ENVIRONMENT_* 变量
- 持久化变量。
environment:url 是 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。

支持所有为作业定义的变量（项目/组变量、.gitlab-ci.yml 变量、触发器变量、流水线计划变量）。

不支持 GitLab Runner config.toml 中定义的变量及作业 script 中创建的变量。
environment:auto_stop_in 是 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。

被替换的变量值应为人类可读的自然语言时间格式。更多信息请参阅 支持值。
environment:kubernetes:agent 是 GitLab 类似 environment:url，但变量扩展不支持：

- CI_ENVIRONMENT_* 变量
- 持久化变量。
environment:kubernetes:namespace 是 GitLab 类似 environment:url，但变量扩展不支持：

- CI_ENVIRONMENT_* 变量
- 持久化变量。
id_tokens:aud 是 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。变量扩展功能于 GitLab 16.1 版本引入。
image 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
include 是 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。

关于支持变量的更多信息，请参阅 在 include 中使用变量。
resource_group 是 GitLab 类似 environment:url，但变量扩展不支持：
- CI_ENVIRONMENT_URL
- 持久化变量。
rules:changes 否 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。
rules:changes:compare_to 否 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。
rules:exists 否 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。
rules:if 否 不适用 变量必须为 $variable 格式。不支持以下变量：

- CI_ENVIRONMENT_SLUG 变量
- 持久化变量。
script 是 脚本执行环境 变量扩展由 脚本执行环境 执行。
services:name 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
services 是 Runner 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行。
tags 是 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。
trigger 和 trigger:project 是 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。trigger:project 的变量扩展功能于 GitLab 15.3 版本引入。
variables 是 GitLab/Runner 变量扩展首先由 GitLab 的 内部变量扩展机制 执行，随后未识别或不可用的变量由 GitLab Runner 的 内部变量扩展机制 执行。
workflow:name 是 GitLab 变量扩展由 GitLab 的 内部变量扩展机制 执行。

支持 workflow 中所有可用变量：
- 项目/组变量
- 全局 variables 和 workflow:rules:variables（当规则匹配时）
- 从父流水线继承的变量
- 触发器变量
- 流水线计划变量

不支持 GitLab Runner config.toml 中定义的变量、作业中定义的变量或 持久化变量。

config.toml 文件

定义项 是否可扩展？ 说明
runners.environment 是 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行
runners.kubernetes.pod_labels 是 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行
runners.kubernetes.pod_annotations 是 变量扩展由 GitLab Runner 的 内部变量扩展机制 执行

关于 config.toml 的更多信息，请参阅 GitLab Runner 文档。

扩展机制

存在三种扩展机制：

  • GitLab
  • GitLab Runner
  • 脚本执行环境

GitLab 内部变量扩展机制

扩展部分需采用 $variable、${variable} 或 %variable% 格式。无论作业由哪个操作系统/Shell 处理，所有格式均以相同方式处理，因为扩展在 Runner 获取作业前由 GitLab 完成。

嵌套变量扩展

GitLab 在将作业发送给 Runner 之前，会递归扩展作业变量值。例如在以下场景中：

- BUILD_ROOT_DIR: '${CI_BUILDS_DIR}'
- OUT_PATH: '${BUILD_ROOT_DIR}/out'
- PACKAGE_PATH: '${OUT_PATH}/pkg'

Runner 接收到的是完整有效的路径。例如若 ${CI_BUILDS_DIR} 为 /output，则 PACKAGE_PATH 将为 /output/out/pkg。

对不可用变量的引用保持原样。此时 Runner 会在运行时 尝试扩展变量值。例如 CI_BUILDS_DIR 变量仅在运行时为 Runner 所知。

GitLab Runner 内部变量扩展机制

  • 支持：项目/组变量、.gitlab-ci.yml 变量、config.toml 变量，以及触发器、流水线计划、手动流水线的变量。
  • 不支持：脚本内定义的变量（例如 export MY_VARIABLE="test"）。

Runner 使用 Go 的 os.Expand() 方法进行变量扩展，这意味着它仅处理定义为 $variable 和 ${variable} 的变量。重要的是扩展仅执行一次，因此嵌套变量可能有效也可能无效，具体取决于变量定义顺序以及 GitLab 中是否启用了 嵌套变量扩展。

对于 artifacts 和 cache 上传，Runner 使用 mvdan.cc/sh/v3/expand 替代 Go 的 os.Expand() 进行变量扩展，因为 mvdan.cc/sh/v3/expand 支持 参数扩展。

脚本执行环境

这是在 script 执行期间发生的扩展阶段。其行为取决于所使用的 Shell（bash、sh、cmd、PowerShell）。例如，如果作业的 script 包含一行 echo $MY_VARIABLE-${MY_VARIABLE_2}，它应由 bash/sh 正确处理（根据变量是否定义返回空值或特定值），但无法与 Windows 的 cmd 或 PowerShell 配合使用，因为这些 Shell 使用不同的变量语法。

支持：

  • script 可使用 Shell 默认的所有可用变量（例如所有 bash/sh Shell 中都存在的 $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 部分中脚本之前定义的变量。
  • 不能使用 before_script 和 script 中定义的变量。

这些限制存在是因为 after_script 脚本在 独立的 Shell 环境 中执行。

持久化变量

部分预定义变量称为持久化变量。持久化变量：

流水线触发作业 不能使用作业级别的持久化变量，但可以使用流水线级别的持久化变量。

部分持久化变量包含令牌，出于安全原因无法在某些定义中使用。

流水线级别持久化变量：

  • CI_PIPELINE_ID
  • CI_PIPELINE_URL

作业级别持久化变量：

  • CI_DEPLOY_PASSWORD
  • CI_DEPLOY_USER
  • CI_JOB_ID
  • CI_JOB_STARTED_AT
  • CI_JOB_TOKEN
  • CI_JOB_URL
  • CI_PIPELINE_CREATED_AT
  • CI_REGISTRY_PASSWORD
  • CI_REGISTRY_USER
  • CI_REPOSITORY_URL

带环境作用域的变量

支持定义带环境作用域的变量。假设在 review/staging/* 作用域中定义了变量 $STAGING_SECRET，则以下使用动态环境的作业将根据匹配的变量表达式创建：

my-job:
  stage: staging
  environment:
    name: review/$CI_JOB_STAGE/deploy
  script:
    - 'deploy staging'
  rules:
    - if: $STAGING_SECRET == 'something'