{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- Offering: JihuLab.com, 私有化部署
{{< /details >}}
正如在 CI/CD 变量 文档中所描述的,您可以定义许多不同的变量。其中一些可以用于所有极狐GitLab CI/CD 功能,但有些则或多或少有限制。
本文档描述了不同类型的变量可以在哪里以及如何使用。
变量使用
定义的变量可以在两个地方使用。在:
- 极狐GitLab 端,在
.gitlab-ci.yml
文件中。 - 极狐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 中可用的所有变量:- 项目/群组变量。 - 全局 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 的 内部变量扩展机制 完成。 |
您可以在 极狐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(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_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'