{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

正如在 CI/CD 变量 文档中所描述的,您可以定义许多不同的变量。其中一些可以用于所有极狐GitLab CI/CD 功能,但有些则或多或少有限制。

本文档描述了不同类型的变量可以在哪里以及如何使用。

变量使用

定义的变量可以在两个地方使用。在:

  1. 极狐GitLab 端,在 .gitlab-ci.yml 文件中。
  2. 极狐GitLab Runner 端,在 config.toml 中。

.gitlab-ci.yml 文件

{{< history >}}

  • CI_ENVIRONMENT_* 变量的支持引入于极狐GitLab 16.4,除了 CI_ENVIRONMENT_SLUG

{{< /history >}}

定义 可以展开? 展开位置 描述
after_script 脚本执行 shell 变量扩展由 执行 shell 环境 完成。
artifacts:name Runner 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。
artifacts:paths Runner 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。
artifacts:exclude Runner 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。
before_script 脚本执行 shell 变量扩展由 执行 shell 环境 完成。
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 的 内部变量扩展机制 完成。

被替换的变量的值应为自然语言形式的时间段。有关更多信息,请参见 支持的值
id_tokens:aud 极狐GitLab 变量扩展由极狐GitLab 的 内部变量扩展机制 完成。变量扩展 introduced in 极狐GitLab 16.1。
image Runner 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。
include 极狐GitLab 变量扩展由极狐GitLab 的 内部变量扩展机制 完成。

有关支持变量的更多信息,请参见 使用变量与包含
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 脚本执行 shell 变量扩展由 执行 shell 环境 完成。
services:name Runner 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。
services Runner 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。
tags 极狐GitLab 变量扩展由极狐GitLab 的 内部变量扩展机制 完成。
trigger and trigger:project 极狐GitLab 变量扩展由极狐GitLab 的 内部变量扩展机制 完成。trigger:project 的变量扩展 introduced in 极狐GitLab 15.3。
variables 极狐GitLab/Runner 变量扩展首先由极狐GitLab 的 内部变量扩展机制 完成,然后任何未识别或不可用的变量由极狐GitLab Runner 的 内部变量扩展机制 进行扩展。
workflow:name 极狐GitLab 变量扩展由极狐GitLab 的 内部变量扩展机制 完成。

支持的是 workflow 中可用的所有变量:
- 项目/群组变量。
- 全局 variablesworkflow:rules:variables(当匹配规则时)。
- 从父流水线继承的变量。
- 来自触发器的变量。
- 来自流水线计划的变量。

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

config.toml 文件

定义 可以展开? 描述
runners.environment 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。
runners.kubernetes.pod_labels 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。
runners.kubernetes.pod_annotations 变量扩展由极狐GitLab Runner 的 内部变量扩展机制 完成。

您可以在 极狐GitLab Runner 文档 中阅读更多关于 config.toml 的内容。

扩展机制

有三种扩展机制:

  • 极狐GitLab
  • 极狐GitLab Runner
  • 执行 shell 环境

极狐GitLab 内部变量扩展机制

扩展部分需要以 $variable${variable}%variable% 的形式出现。每种形式的处理方式相同,无论哪个操作系统/shell 处理作业,因为扩展是在极狐GitLab 中完成的,任何 runner 都没有获取作业。

嵌套变量扩展

极狐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 中是否启用了嵌套变量扩展

对于产物和缓存上传,runner 使用 mvdan.cc/sh/v3/expand 进行变量扩展,而不是 Go 的 os.Expand(),因为 mvdan.cc/sh/v3/expand 支持参数扩展。

执行 shell 环境

这是在 script 执行期间发生的扩展阶段。其行为取决于使用的 shell(bashshcmd、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_scriptscript 中定义的变量。

这些限制存在是因为 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_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'