默认环境变量

4853 字约 16 分钟

默认环境变量 列出 云原生构建 内置的只读环境变量。

使用场景：脚本里需要读取构建上下文时查阅——例如取分支名、Commit SHA、合并请求编号，或在通知里拼出构建详情链接。这些变量由平台注入，构建过程中无法覆盖。

下文的合并类事件包括：

pull_request
pull_request.update
pull_request.target
pull_request.approved
pull_request.changes_requested
pull_request.mergeable
pull_request.merged
pull_request.comment

更多触发事件请参考触发事件。

使用方式

以下列出的内置变量会在流水线运行时自动注入到每个 Job 的执行环境，可直接在 script 或 commands 中以 ${变量名} 引用，无需手动声明。下面以 main 分支收到 push 事件为例：

.cnb.yml
main:
  push:
    - name: show-builtin-env
      stages:
        - name: print-vars
          script: |
            echo "branch: ${CNB_BRANCH}"
            echo "commit: ${CNB_COMMIT_SHORT}"
            echo "repo: ${CNB_REPO_SLUG}"
            echo "build id: ${CNB_BUILD_ID}"

示例中用到的 ${CNB_BRANCH}、${CNB_COMMIT_SHORT}、${CNB_REPO_SLUG}、${CNB_BUILD_ID} 分别对应下文分支、提交、仓库、构建各类变量。

提示

内置变量均为只读，构建过程中无法覆盖；如需自定义或跨步骤传递环境变量，请参考自定义环境变量。

基础变量

变量概览

变量名	说明
CI	CI 标识，值为 `true`
CNB	CNB 标识，值为 `true`
CNB_WEB_PROTOCOL	Web 使用的协议
CNB_WEB_HOST	Web 使用的 HOST
CNB_WEB_ENDPOINT	Web 完整地址
CNB_API_ENDPOINT	API 完整地址
CNB_GROUP_SLUG	仓库所属父组织路径
CNB_GROUP_SLUG_LOWERCASE	父组织路径小写格式
CNB_GROUP_ID	仓库所属父组织 ID
CNB_ROOT_SLUG	仓库所属根组织路径
CNB_ROOT_SLUG_LOWERCASE	根组织路径小写格式
CNB_ROOT_ID	仓库所属根组织 ID
CNB_EVENT	触发构建的事件名称
CNB_EVENT_URL	事件相关链接
CNB_BRANCH	分支名或 Tag 名
CNB_BRANCH_SHA	分支最近提交的 SHA
CNB_DEFAULT_BRANCH	仓库默认分支
CNB_TOKEN_USER_NAME	临时令牌对应的用户名
CNB_TOKEN	流水线运行期临时令牌
TWINE_USERNAME	PyPI 制品库用户名
TWINE_PASSWORD	PyPI 制品库密码
CNB_IS_CRONEVENT	是否为定时任务事件
CNB_DOCKER_REGISTRY	制品库 Docker 源地址
CNB_DOCKER_MODEL_REGISTRY	制品库 Docker Model 源地址
CNB_HELM_REGISTRY	制品库 Helm 源地址
CNB_HAS_LFS_FILES	是否存在 LFS 文件

CI

值为 true，用于标识当前环境为 CI 环境。

CNB

值为 true，用于标识当前环境为 CNB 构建环境。

CNB_WEB_PROTOCOL

当前 Web 使用的协议，取值为 http 或 https。

CNB_WEB_HOST

当前 Web 使用的 HOST。

CNB_WEB_ENDPOINT

当前 Web 的完整地址，包含协议、HOST 和路径（如有）。

CNB_API_ENDPOINT

当前 API 的完整地址，包含协议、HOST 和路径（如有）。

可与 CNB_TOKEN 配合在 CI 中调用 API。

CNB_GROUP_SLUG

仓库所属父组织的路径。

CNB_GROUP_SLUG_LOWERCASE

仓库所属父组织路径的小写格式。

CNB_GROUP_ID

仓库所属父组织 ID。

CNB_ROOT_SLUG

仓库所属根组织的路径。

CNB_ROOT_SLUG_LOWERCASE

仓库所属根组织路径的小写格式。

CNB_ROOT_ID

仓库所属根组织 ID。

CNB_EVENT

值为触发构建的事件名称。

事件类型参见事件。

CNB_EVENT_URL

事件相关链接，取值规则如下：

触发事件	变量值
合并类事件	PR 的链接
Issue 类事件	Issue 的链接
其他事件	CNB_COMMIT 的链接

CNB_BRANCH

分支名或 Tag 名，取值规则如下：

触发事件	变量值
合并类事件	目标分支名
Tag 类事件	Tag 名
其他事件	对应的分支名称

CNB_BRANCH_SHA

分支最近一次提交的 SHA，取值规则：

触发事件	变量值
`branch.delete`	无值
其他事件	`CNB_BRANCH` 最近一次提交的 SHA

CNB_DEFAULT_BRANCH

仓库默认分支。

CNB_TOKEN_USER_NAME

用户临时令牌对应的用户名，固定为 cnb。

CNB_TOKEN

流水线运行期间的临时令牌，结束后自动销毁，可用于代码和制品的拉取与推送，以及 API 调用。

权限分配

权限取决于触发流水线的事件类型，分为三类：

开启工作模式的 NPC 事件
未开启工作模式的 NPC 事件或其他不可信事件（参考不可信事件）
其他可信事件

api_trigger 默认归入其他可信事件。若构建以 NPC 为代理人运行， token 权限按是否开启工作模式归入对应 NPC 事件分类，规则与原生 NPC 事件一致，参见通过 API 以 NPC 身份触发。

开启工作模式的 NPC 事件：

权限项	说明
`repo-code:rw`	代码读写
`repo-pr:rw`	PR 读写
`repo-issue:rw`	Issue 读写
`repo-notes:rw`	评论读写
`repo-release:rw`	Release 读写
`repo-basic-info:r`	基本信息只读
`account-profile:r`	用户信息只读
`account-engage:r`	用户关注的仓库、关注者只读
`registry-package:rw`	制品库读写
`repo-cnb-trigger:rw`	触发器读写
`repo-cnb-history:r`	构建历史只读
`repo-cnb-detail:r`	构建详情只读

未开启工作模式的 NPC 事件或其他不可信事件：

权限项	说明
`repo-code:r`	代码只读
`repo-pr:r`	PR 只读
`repo-issue:rw`	Issue 读写
`repo-notes:rw`	评论读写
`repo-release:r`	Release 只读
`repo-basic-info:r`	基本信息只读
`registry-package:r`	制品库只读
`account-profile:r`	用户信息只读

其他可信事件：

权限项	说明
`repo-code:rw`	代码读写
`repo-pr:rw`	PR 读写
`repo-issue:rw`	Issue 读写
`repo-notes:rw`	评论读写
`repo-release:rw`	Release 读写
`registry-package:rw`	制品库读写
`repo-cnb-trigger:rw`	触发器读写
`repo-cnb-history:r`	构建历史只读
`repo-cnb-detail:r`	构建详情只读
`repo-basic-info:r`	基本信息，只读
`repo-manage:r`	仓库管理只读
`account-profile:r`	用户信息只读
`account-engage:r`	用户关注的仓库、关注者只读
`group-resource:r`	组织资源只读

权限说明

各权限的具体含义请参考个人设置 > 访问令牌。

安全限制

公开仓库的流水线，该令牌仅能访问公开仓库/制品库。
Fork 仓库的流水线，该令牌仅能访问当前仓库：fork 仓库执行的是继承自上游的 .cnb.yml （第三方编写），因此不适用「允许不可信事件跨仓操作」管控。
NPC 事件的流水线，以及以 NPC 为代理人运行的 api_trigger 流水线，该令牌仅能访问当前仓库。跨仓 Fork PR 的 pull_request.comment@npc 事件中，若触发者为 PR 提交者，则仅能访问公开仓库/制品库。
不可信事件（参考不可信事件）的流水线，该令牌仅能访问当前仓库；根组织管理员在「组织设置 → 云原生构建管控」中开启 允许不可信事件跨仓操作后，可访问根组织下所有仓库（仍不可跨根组织）。 Fork 仓库的流水线除外，详见上一条。
定时任务的流水线，该令牌仅能访问当前仓库；根组织开启 允许定时任务跨仓操作后，可访问根组织下所有仓库。

提示

上述范围限定只作用于 CNB_TOKEN。拉取代码、拉取 CNB 制品库镜像使用独立的只读令牌，不受影响，跨仓 PR 场景的源仓库代码拉取正常。

若仓库已清空 LFS 文件，Git GC 前该变量仍为 true。

提交类变量

提交类变量概览

变量名	说明
CNB_BEFORE_SHA	分支推送前最近一次提交的 SHA
CNB_COMMIT	构建对应的代码 SHA
CNB_COMMIT_SHORT	CNB_COMMIT 前 8 位字符
CNB_COMMIT_MESSAGE	提交信息
CNB_COMMIT_MESSAGE_TITLE	提交信息标题
CNB_COMMITTER	提交者
CNB_COMMITTER_EMAIL	提交者邮箱
CNB_NEW_COMMITS_COUNT	新增提交数量
CNB_IS_TAG	是否为 Tag 构建
CNB_TAG_MESSAGE	Tag 消息
CNB_TAG_RELEASE_TITLE	Release 标题
CNB_TAG_RELEASE_DESC	Release 描述
CNB_TAG_IS_RELEASE	Tag 是否有对应 Release
CNB_TAG_IS_PRE_RELEASE	是否为预发布 Release
CNB_IS_NEW_BRANCH	是否为新创建的分支
CNB_IS_NEW_BRANCH_WITH_UPDATE	是否为新分支且带新提交

CNB_BEFORE_SHA

分支推送前，远端该分支最近一次提交的 SHA。

取值规则:

触发事件	变量值
`push`、`commit.add`	分支推送前最近一次提交的 SHA
新建分支	`0000000000000000000000000000000000000000`
`branch.create`	`0000000000000000000000000000000000000000`

CNB_COMMIT

构建时对应的代码 SHA。

SHA 取值与工作区代码版本的对应关系如下：

触发事件	变量值	工作区
`push`	最后一次提交的 SHA	目标分支
`commit.add`	最后一次提交的 SHA	目标分支
`tag_push`	该 Tag 最后一次提交的 SHA	目标 TAG
`tag_deploy.*`	该 Tag 最后一次提交的 SHA	目标 TAG
`auto_tag`	默认分支最后一次提交的 SHA	默认分支
`branch.create`	新分支最后一次提交的 SHA	新分支
`branch.delete`	默认分支最后一次提交的 SHA	默认分支
`issue.*`	默认分支最后一次提交的 SHA	默认分支
`issue.comment@npc`	默认分支最后一次提交的 SHA	默认分支
`pull_request`	源分支最后一次提交的 SHA	预合并
`pull_request.merged`	合并后的 SHA	目标分支
`pull_request.target`	目标分支最后一次提交的 SHA	目标分支
`pull_request.mergeable`	目标分支最后一次提交的 SHA	预合并
`pull_request.approved`	源分支最后一次提交的 SHA	预合并
`pull_request.changes_requested`	源分支最后一次提交的 SHA	预合并
`pull_request.comment`	源分支最后一次提交的 SHA	预合并
`pull_request.comment@npc`	默认分支最后一次提交的 SHA	源分支
`vscode`	指定分支最后一次提交的 SHA	目标分支
`web_trigger.*`	指定分支最后一次提交的 SHA	目标分支

条件	变量值
分支为 Tag 且存在对应的 Release	`true`
其他情况	`false`

CNB_TAG_IS_PRE_RELEASE

是否为预发布版本。

取值规则:

条件	变量值
分支为 Tag，存在对应的 Release，且为预发布	`true`
其他情况	`false`

变量名	说明
CNB_REPO_SLUG	仓库路径
CNB_REPO_SLUG_LOWERCASE	仓库路径小写格式
CNB_REPO_NAME	仓库名称
CNB_REPO_NAME_LOWERCASE	仓库名称小写格式
CNB_REPO_ID	仓库 ID
CNB_REPO_URL_HTTPS	仓库 HTTPS 地址

变量名	说明
CNB_BUILD_ID	构建流水号
CNB_BUILD_WEB_URL	构建日志地址
CNB_BUILD_START_TIME	构建开始时间
CNB_BUILD_USER	触发者用户名
CNB_BUILD_USER_NICKNAME	触发者昵称
CNB_BUILD_USER_EMAIL	触发者邮箱
CNB_BUILD_USER_ID	触发者 ID
CNB_BUILD_USER_NPC_SLUG	NPC 所属仓库路径
CNB_BUILD_USER_NPC_NAME	NPC 角色名
CNB_BUILD_STAGE_NAME	Stage 名称
CNB_BUILD_JOB_NAME	Job 名称
CNB_BUILD_JOB_KEY	Job Key
CNB_BUILD_WORKSPACE	工作空间根目录
CNB_BUILD_FAILED_MSG	构建失败错误信息
CNB_BUILD_FAILED_STAGE_NAME	失败的 Stage 名称
CNB_PIPELINE_NAME	Pipeline 名称
CNB_PIPELINE_KEY	Pipeline Key
CNB_PIPELINE_ID	Pipeline ID
CNB_PIPELINE_DOCKER_IMAGE	Pipeline Docker 镜像
CNB_PIPELINE_STATUS	Pipeline 构建状态
CNB_PIPELINE_MAX_RUN_TIME	流水线最大运行时间
CNB_RUNNER_IP	Runner IP
CNB_RUNNER_VERSION	Runner 版本号
CNB_CPUS	可用 CPU 核数
CNB_MEMORY	可用内存大小
CNB_IS_RETRY	是否由 rebuild 触发
HUSKY_SKIP_INSTALL	Husky 兼容标识

状态值	说明
`success`	流水线构建成功完成
`error`	流水线构建过程中发生错误
`cancel`	流水线构建被取消

变量名	说明
CNB_PULL_REQUEST	是否为 PR 触发
CNB_PULL_REQUEST_LIKE	是否为合并类事件触发
CNB_PULL_REQUEST_PROPOSER	PR 提出者
CNB_PULL_REQUEST_TITLE	PR 标题
CNB_PULL_REQUEST_DESCRIPTION	PR 描述
CNB_PULL_REQUEST_BRANCH	PR 源分支名称
CNB_PULL_REQUEST_SHA	PR 源分支最新 SHA
CNB_PULL_REQUEST_TARGET_SHA	PR 目标分支最新 SHA
CNB_PULL_REQUEST_MERGE_SHA	PR 合并后 SHA
CNB_PULL_REQUEST_SLUG	源仓库 Slug
CNB_PULL_REQUEST_ACTION	PR 操作类型
CNB_PULL_REQUEST_ID	PR 全局唯一 ID
CNB_PULL_REQUEST_IID	PR 仓库编号
CNB_PULL_REQUEST_REVIEWERS	评审人列表
CNB_PULL_REQUEST_REVIEW_STATE	评审状态
CNB_REVIEW_REVIEWED_BY	同意评审人列表
CNB_REVIEW_LAST_REVIEWED_BY	最后同意评审人
CNB_PULL_REQUEST_IS_WIP	PR 是否为 WIP

CNB_PULL_REQUEST

是否为 PR 触发。

取值规则:

触发事件	变量值
`pull_request`、`pull_request.update`、`pull_request.target`	`true`
其他事件	`false`

CNB_PULL_REQUEST_LIKE

是否为合并类事件触发。

取值规则:

触发事件	变量值
合并类事件	`true`
其他事件	`false`

触发事件	变量值
`pull_request.merged`	PR 合并后的 SHA
`pull_request`	PR 预合并后的 SHA
`pull_request.update`	PR 预合并后的 SHA
`pull_request.target`	PR 预合并后的 SHA
`pull_request.mergeable`	PR 预合并后的 SHA
`pull_request.comment`	PR 预合并后的 SHA
其他事件	无值

CNB_PULL_REQUEST_SLUG

合并类事件中，源仓库的路径，格式为 group_slug/repo_name 或 group_slug/sub_group_slug/.../repo_name。

CNB_PULL_REQUEST_ACTION

PR 操作类型。

可能的值:

值	说明
`opened`	新建 PR
`edited`	PR 编辑
`synchronize`	源分支 push
`submitted`	评审
`ready_for_merge`	评审通过或 CI 状态变更时 PR 变成可合并

条件	变量值
有评审者且有人通过评审	`approve`
有评审者但无人通过评审	`unapprove`
其他情况	无值

触发事件	变量值
合并类事件	`true` 或 `false`
其他事件	无值

云原生开发类变量

云原生开发类变量概览

变量名	说明
CNB_VSCODE_WEB_URL	云原生开发地址
CNB_VSCODE_MAX_RUN_TIME	云原生开发最大运行时间

变量名	说明
CNB_ISSUE_ID	Issue 全局唯一 ID
CNB_ISSUE_IID	Issue 仓库编号
CNB_ISSUE_TITLE	Issue 标题
CNB_ISSUE_DESCRIPTION	Issue 描述
CNB_ISSUE_OWNER	Issue 作者
CNB_ISSUE_STATE	Issue 状态
CNB_ISSUE_IS_RESOLVED	Issue 是否已解决
CNB_ISSUE_ASSIGNEES	Issue 处理人列表
CNB_ISSUE_LABELS	Issue 标签列表
CNB_ISSUE_PRIORITY	Issue 优先级

触发事件	变量值
`issue.*`	`open` 或 `closed`
其他事件	空字符串

CNB_ISSUE_IS_RESOLVED

Issue 是否被解决。

取值规则:

触发事件	变量值
`issue.*`	`true` 或 `false`
其他事件	空字符串

变量名	说明
CNB_COMMENT_ID	评论全局唯一 ID
CNB_COMMENT_BODY	评论内容
CNB_COMMENT_TYPE	评论类型
CNB_COMMENT_FILE_PATH	评论所在文件
CNB_COMMENT_RANGE	评论所在代码行
CNB_COMMENT_SHA	评论针对的提交
CNB_REVIEW_ID	评审 ID
CNB_REVIEW_DESCRIPTION	评审描述

评论类型	变量值
PR 代码评审评论	`diff_note`
PR 非代码评审评论以及 Issue 评论	`note`
其他情况	无值

变量名	说明
CNB_NPC_SLUG	NPC 所属仓库路径
CNB_NPC_SLUG_LOWERCASE	NPC 所属仓库路径（小写格式）
CNB_NPC_NAME	NPC 角色名
CNB_NPC_SHA	NPC 仓库默认分支最新 SHA
CNB_NPC_PROMPT	NPC 角色提示词
CNB_NPC_SLOGAN	NPC 角色口号
CNB_NPC_AVATAR	NPC 角色头像
CNB_NPC_ENABLE_THINKING	NPC 是否开启思考
CNB_NPC_ENABLE_WORKMODE	NPC 是否开启工作模式
CNB_NPC_TRIGGER_CONTENT	触发 NPC 的内容

触发场景	等效环境变量
创建 Issue 的描述	CNB_ISSUE_DESCRIPTION
Issue 评论	CNB_COMMENT_BODY
创建 PR 的描述	CNB_PULL_REQUEST_DESCRIPTION
PR 评审	CNB_REVIEW_DESCRIPTION
PR 评论	CNB_COMMENT_BODY
PR 评审评论	CNB_COMMENT_BODY