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

预定义的CI/CD变量参考

层级：免费版、高级版、旗舰版
提供方式：GitLab.com、GitLab 自托管、GitLab 专用

每个 GitLab CI/CD 流水线都提供了预定义的 CI/CD 变量。

避免覆盖预定义变量，因为这可能导致流水线行为异常。

变量的可用性

预定义变量在流水线执行的三个不同阶段变得可用：

预流水线（Pre-pipeline）：预流水线变量在创建流水线之前可用。这些变量是唯一可用于 include:rules 的变量，用于控制创建流水线时使用的配置文件。
流水线（Pipeline）：当 GitLab 创建流水线时，流水线变量变得可用。与预流水线变量一起，流水线变量可用于配置作业中定义的 rules，以确定将哪些作业添加到流水线中。
仅作业（Job-only）：这些变量仅在运行器（runner）获取并执行作业时对每个作业可用，并且：
- 可用于作业脚本中。
- 不能与触发作业一起使用。
- 不能与 workflow、include 或 rules 一起使用。

预定义变量

变量	可用性	说明
`CHAT_CHANNEL`	流水线	触发 ChatOps 命令的源聊天频道。
`CHAT_INPUT`	流水线	随 ChatOps 命令传递的额外参数。
`CHAT_USER_ID`	流水线	触发 ChatOps 命令的用户在聊天服务中的用户ID。
`CI`	预流水线	所有在CI/CD中执行的任务都可用。当可用时为 `true`。
`CI_API_V4_URL`	预流水线	GitLab API v4 根URL。
`CI_API_GRAPHQL_URL`	预流水线	GitLab API GraphQL 根URL。GitLab 15.11 引入。
`CI_BUILDS_DIR`	仅任务	执行构建的顶级目录。
`CI_COMMIT_AUTHOR`	预流水线	提交作者，格式为 `姓名 <邮箱>`。
`CI_COMMIT_BEFORE_SHA`	预流水线	分支或标签上之前的最新提交。对于合并请求流水线、计划流水线、分支或标签的第一个提交流水线，或手动运行流水线时，始终为 `0000000000000000000000000000000000000000`。
`CI_COMMIT_BRANCH`	预流水线	提交分支名称。在分支流水线（包括默认分支流水线）中可用。在合并请求流水线或标签流水线中不可用。
`CI_COMMIT_DESCRIPTION`	预流水线	提交描述。如果标题短于100个字符，则为消息的第一行以外的内容。
`CI_COMMIT_MESSAGE`	预流水线	完整的提交信息。
`CI_COMMIT_REF_NAME`	预流水线	为其构建项目的分支或标签名称。
`CI_COMMIT_REF_PROTECTED`	预流水线	如果作业正在受保护的引用下运行，则为 `true`；否则为 `false`。
`CI_COMMIT_REF_SLUG`	预流水线	`CI_COMMIT_REF_NAME` 转换为小写，缩短至63字节，并将除 `0-9` 和 `a-z` 以外的所有字符替换为 `-`。无前导/尾随 `-`。用于URL、主机名和域名。
`CI_COMMIT_SHA`	预流水线	项目构建所用的提交版本。
`CI_COMMIT_SHORT_SHA`	预流水线	`CI_COMMIT_SHA` 的前八个字符。
`CI_COMMIT_TAG`	预流水线	提交标签名称。仅在标签流水线中可用。
`CI_COMMIT_TAG_MESSAGE`	预流水线	提交标签信息。仅在标签流水线中可用。GitLab 15.5 引入。
`CI_COMMIT_TIMESTAMP`	预流水线	提交的时间戳，格式为 ISO 8601。例如：`2022-01-31T16:47:55Z`。默认为UTC。
`CI_COMMIT_TITLE`	预流水线	提交标题。消息的第一行完整内容。
`CI_CONCURRENT_ID`	仅任务	单个执行器中构建执行的唯一ID。
`CI_CONCURRENT_PROJECT_ID`	仅任务	单个项目和单个执行器中构建执行的唯一ID。
`CI_CONFIG_PATH`	预流水线	CI/CD配置文件的路径。默认为 `.gitlab-ci.yml`。
`CI_DEBUG_TRACE`	流水线	如果启用了调试日志记录（跟踪），则为 `true`。
`CI_DEBUG_SERVICES`	流水线	如果启用了服务容器日志记录，则为 `true`。GitLab 15.7 引入。需要GitLab Runner 15.7。
`CI_DEFAULT_BRANCH`	预流水线	项目的默认分支名称。
`CI_DEFAULT_BRANCH_SLUG`	预流水线	`CI_DEFAULT_BRANCH` 转换为小写，缩短至63字节，并将除 `0-9` 和 `a-z` 以外的所有字符替换为 `-`。无前导/尾随 `-`。用于URL、主机名和域名。
`CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX`	预流水线	通过依赖代理拉取镜像的直接组镜像前缀。
`CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`	预流水线	通过依赖代理拉取镜像的顶级组镜像前缀。

合并请求管道的预定义变量

这些变量在 GitLab 创建管道之前可用（预管道）。这些变量可以与 include:rules 结合使用，也可作为作业中的环境变量。

管道必须是合并请求管道，且合并请求必须处于打开状态。

变量	描述
`CI_MERGE_REQUEST_APPROVED`	合并请求的批准状态。当合并请求批准可用且合并请求已被批准时为 `true`。
`CI_MERGE_REQUEST_ASSIGNEES`	合并请求分配者的用户名列表，以逗号分隔。仅当合并请求至少有一个分配者时可用。
`CI_MERGE_REQUEST_DIFF_BASE_SHA`	合并请求差异的基础 SHA 值。
`CI_MERGE_REQUEST_DIFF_ID`	合并请求差异的版本。
`CI_MERGE_REQUEST_EVENT_TYPE`	合并请求的事件类型。可为 `detached`、`merged_result` 或 `merge_train`。
`CI_MERGE_REQUEST_DESCRIPTION`	合并请求的描述。若描述超过 2700 个字符，则该变量中仅存储前 2700 个字符。GitLab 16.7 引入。
`CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED`	若因合并请求描述过长而被截断至 2700 个字符（即 `CI_MERGE_REQUEST_DESCRIPTION` 被截断），则为 `true`；否则为 `false`。GitLab 16.8 引入。
`CI_MERGE_REQUEST_ID`	合并请求的实例级 ID。此 ID 在 GitLab 实例的所有项目中唯一。
`CI_MERGE_REQUEST_IID`	合并请求的项目级 IID（内部 ID）。此 ID 对当前项目唯一，也是合并请求 URL、页面标题及其他可见位置使用的编号。
`CI_MERGE_REQUEST_LABELS`	合并请求的标签名称列表，以逗号分隔。仅当合并请求至少有一个标签时可用。
`CI_MERGE_REQUEST_MILESTONE`	合并请求的里程碑标题。仅当合并请求设置了里程碑时可用。
`CI_MERGE_REQUEST_PROJECT_ID`	合并请求所属项目的 ID。
`CI_MERGE_REQUEST_PROJECT_PATH`	合并请求所属项目的路径。例如 `namespace/awesome-project`。
`CI_MERGE_REQUEST_PROJECT_URL`	合并请求所属项目的 URL。例如 `http://192.168.10.15:3000/namespace/awesome-project`。
`CI_MERGE_REQUEST_REF_PATH`	合并请求的引用路径。例如 `refs/merge-requests/1/head`。
`CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`	合并请求的源分支名称。
`CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED`	当合并请求的源分支为受保护分支时为 `true`。GitLab 16.4 引入。
`CI_MERGE_REQUEST_SOURCE_BRANCH_SHA`	合并请求源分支的 HEAD SHA 值。在合并请求管道中该变量为空。仅在合并结果管道中存在此 SHA 值。
`CI_MERGE_REQUEST_SOURCE_PROJECT_ID`	合并请求源项目的 ID。
`CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`	合并请求源项目的路径。
`CI_MERGE_REQUEST_SOURCE_PROJECT_URL`	合并请求源项目的 URL。
`CI_MERGE_REQUEST_SQUASH_ON_MERGE`	当设置 squash 合并选项时为 `true`。GitLab 16.4 引入。
`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`	合并请求的目标分支名称。
`CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED`	当合并请求的目标分支为受保护分支时为 `true`。GitLab 15.2 引入。
`CI_MERGE_REQUEST_TARGET_BRANCH_SHA`	合并请求目标分支的 HEAD SHA 值。在合并请求管道中该变量为空。仅在合并结果管道中存在此 SHA 值。
`CI_MERGE_REQUEST_TITLE`	合并请求的标题。
`CI_MERGE_REQUEST_DRAFT`	若合并请求为草稿状态则为 `true`。引入于 GitLab 17.10。

外部拉取请求流水线的预定义变量

这些变量仅在以下情况可用：

流水线是外部拉取请求流水线
拉取请求处于打开状态。

变量	描述
`CI_EXTERNAL_PULL_REQUEST_IID`	来自 GitHub 的拉取请求 ID。
`CI_EXTERNAL_PULL_REQUEST_SOURCE_REPOSITORY`	拉取请求的源仓库名称。
`CI_EXTERNAL_PULL_REQUEST_TARGET_REPOSITORY`	拉取请求的目标仓库名称。
`CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME`	拉取请求的源分支名称。
`CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA`	拉取请求源分支的 HEAD SHA 值。
`CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME`	拉取请求的目标分支名称。
`CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA`	拉取请求目标分支的 HEAD SHA 值。

部署变量

负责部署配置的集成可以自行定义预定义变量，这些变量会在构建环境中设置。这些变量仅针对部署作业定义。

例如，Kubernetes 集成定义了可与该集成一起使用的部署变量。

每个集成的文档会说明该集成是否有可用的部署变量。

Auto DevOps 变量

当Auto DevOps 启用时，一些额外的预流水线变量会变得可用：

AUTO_DEVOPS_EXPLICITLY_ENABLED：值为 1 表示 Auto DevOps 已启用。
STAGING_ENABLED：参见 Auto DevOps 部署策略。
INCREMENTAL_ROLLOUT_MODE：参见 Auto DevOps 部署策略。
INCREMENTAL_ROLLOUT_ENABLED：已废弃。

集成变量

某些集成在作业中提供变量。这些变量作为作业专属的预定义变量可用：

Harbor：
- HARBOR_URL
- HARBOR_HOST
- HARBOR_OCI
- HARBOR_PROJECT
- HARBOR_USERNAME
- HARBOR_PASSWORD
Apple App Store Connect：
- APP_STORE_CONNECT_API_KEY_ISSUER_ID
- APP_STORE_CONNECT_API_KEY_KEY_ID
- APP_STORE_CONNECT_API_KEY_KEY
- APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64
Google Play：
- SUPPLY_PACKAGE_NAME
- SUPPLY_JSON_KEY_DATA
Diffblue Cover：
- DIFFBLUE_LICENSE_KEY
- DIFFBLUE_ACCESS_TOKEN_NAME
- DIFFBLUE_ACCESS_TOKEN

故障排除

你可以通过 script 命令输出作业中所有可用变量的值。