可以使用变量的地方

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

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

变量使用

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

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

.gitlab-ci.yml 文件

定义 可以扩展吗？ 扩展位置 描述
after_script yes Script execution shell 变量扩展由 execution shell 环境进行
artifacts:name yes Runner 变量扩展由极狐GitLab Runner 的 shell 环境进行
before_script yes Script execution shell 变量扩展由 execution shell 环境进行
cache:key yes Runner 变量扩展是通过极狐GitLab Runner 中的内部变量扩展机制进行的。
environment:name yes 极狐GitLab 类似于 environment:url，但变量扩展不支持以下内容：

- CI_ENVIRONMENT_* 变量。
- 持久变量。
environment:url yes 极狐GitLab 变量扩展是通过极狐GitLab 中的内部变量扩展机制进行的。

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

不支持在极狐GitLab Runner config.toml 中定义的变量和在作业的 script 中创建的变量。
except:variables no n/a 变量必须采用 $variable 的形式。不支持的有以下几种：

- CI_ENVIRONMENT_* 变量，支持的 CI_ENVIRONMENT_NAME 除外。
- 持久变量。
image yes Runner 变量扩展是通过极狐GitLab Runner 中的内部变量扩展机制进行的。
include yes 极狐GitLab 变量扩展是通过极狐GitLab 中的内部变量扩展机制进行的。

支持预定义的项目变量：GITLAB_FEATURES、CI_DEFAULT_BRANCH，以及所有以CI_PROJECT_ 开头的变量（例如CI_PROJECT_NAME）。
only:variables no n/a 变量必须采用 $variable 的形式。不支持的有以下几种：

- CI_ENVIRONMENT_* 变量，支持的 CI_ENVIRONMENT_NAME 除外。
- 持久变量。
resource_group yes 极狐GitLab 类似于 environment:url，但变量扩展不支持以下内容：
- CI_ENVIRONMENT_URL
- 持久变量
rules:changes yes GitLab 变量扩展是通过极狐GitLab 中的内部变量扩展机制进行的。
rules:exists yes GitLab 变量扩展是通过极狐GitLab 中的内部变量扩展机制进行的。
rules:if no n/a 变量必须采用 $variable 的形式。不支持的有以下几种：

- CI_ENVIRONMENT_* 变量，支持的 CI_ENVIRONMENT_NAME 除外。
- 持久变量。
script yes Script execution shell 变量扩展由 execution shell 环境进行
services:name yes Runner 变量扩展是通过极狐GitLab Runner 中的内部变量扩展机制进行的。
services yes Runner 变量扩展是通过极狐GitLab Runner 中的内部变量扩展机制进行的。
tags yes 极狐GitLab 变量扩展是通过极狐GitLab 中的内部变量扩展机制进行的。引入于 14.1 版本。
variables yes 极狐GitLab/Runner 变量扩展首先由极狐GitLab 中的内部变量扩展机制进行，然后任何无法识别或不可用的变量由极狐GitLab Runner 的内部变量扩展机制扩展。
workflow:name yes 极狐GitLab 变量扩展由极狐GitLab 的内部变量扩展机制internal variable expansion mechanism完成。

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

极狐GitLab Runner 配置文件 config.toml 中定义的变量以及作业中定义的变量是不被支持的。持久化变量。

config.toml 文件

定义 可以扩展吗？ 描述
runners.environment yes 变量扩展是通过极狐GitLab Runner 中的内部变量扩展机制进行的。
runners.kubernetes.pod_labels yes 变量扩展是通过极狐GitLab Runner 中的内部变量扩展机制进行的。
runners.kubernetes.pod_annotations yes 变量扩展是通过极狐GitLab Runner 中的内部变量扩展机制进行的。

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

扩展机制

存在三种扩展机制：

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

极狐GitLab 内部变量扩展机制

展开的部分需要是 $variable，或者 ${variable} 或者 %variable% 的形式。 无论哪个 OS/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 中启用了嵌套变量扩展。

执行 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'