触发规则

3064 字约 10 分钟

当 云原生构建 接收到各类事件时，会自动从仓库对应分支获取 .cnb.yml 配置文件，解析出该分支下对应事件的流水线配置，并分配 Runner 执行构建任务。

触发机制概述

云原生构建 支持多种事件触发方式，主要包括：

事件类型	说明
Git 操作事件	代码推送、分支创建、PR 操作等
页面操作事件	手动触发、按钮点击、AI 功能操作等
API 请求事件	通过 OPENAPI 或内置任务触发
定时任务事件	按预定时间计划触发
Issue 事件	Issue 操作、评论等
NPC 事件	Issue、PR 的描述或评论中 `@npc` 时触发

触发流程示例

以 main 分支代码 push 事件为例，触发流程如下:

代码示例：

.cnb.yml
main: # 触发分支
  push: # 触发事件，对应一个构建，可以包含多条 Pipeline。即可以是数组，也可以是对象。
    - stages: # 流水线 1
        - echo "do some job"
    - stages: # 流水线 2
        - echo "do some job"

Fork 仓库触发限制

公开仓库允许他人 Fork。出于安全考虑，Fork 后的仓库在以下类型的事件中，默认不会执行对应的流水线：

Git 操作事件
定时任务事件
Issue 事件

启用 Fork 仓库自动触发

如需允许这些事件触发流水线，可在仓库页面依次进入 设置 → 云原生构建，并勾选以下选项：

设置选项	说明
允许自动触发	选中后，仓库将按照 .cnb.yml 配置自动触发云原生构建
Fork 的仓库默认允许自动触发	选中后，由本仓 Fork 出来的仓库将按照 .cnb.yml 配置自动触发云原生构建

安全提示：Fork 后的仓库在执行流水线时，其默认环境变量 CNB_TOKEN 的权限范围仅限于 当前仓库，以确保安全性。

触发分支

触发分支指代码仓库中触发事件的分支，用于匹配对应的流水线配置。

重要提示

在某个分支下配置其他分支的流水线，并不会使其他分支的事件按此配置执行。实际执行取决于各分支自身 .cnb.yml 文件的配置。

匹配模式

分支名称支持 glob 模式匹配（了解 glob 匹配）。

常用匹配规则

.cnb.yml
.push_pipeline: &push_pipeline
  stages:
    - name: do something
      script: echo "do something"

# 匹配以 dev/ 开头的所有分支
"dev/*":
  push:
    - *push_pipeline

# 匹配 main 或 dev 分支
"(main|dev)":
  push:
    - *push_pipeline

# 匹配除 main 和 dev 以外的所有分支
"**/!(main|dev)":
  push:
    - *push_pipeline

# 匹配所有分支
"**":
  push:
    - *push_pipeline

# 兜底，匹配没有 glob 匹配的分支
"$":
  push:
    - *push_pipeline
  tag_push:
    - *push_pipeline

匹配策略

系统分阶段按优先级进行分支匹配，只有前一阶段未匹配时才会进入下一阶段：

优先级	匹配阶段	说明
1	glob 模式匹配	尝试用所有 glob 规则匹配分支名
2	兜底匹配	使用 `$` 规则匹配所有未被 glob 匹配的分支

并行执行：如果多个 glob 规则同时匹配，所有匹配规则的流水线将并行执行。

触发事件

Git 操作事件

Branch 事件

由远端代码分支变动触发的事件。

事件名	触发时机	说明
push	分支推送时触发	最常用的触发事件
commit.add	分支推送包含新提交时触发	会额外提供环境变量 `CNB_NEW_COMMITS_COUNT`（新增的 Commits 数量），可结合 `git log -n` 查看新增的 Commits
branch.create	分支创建时触发	同时会触发 `push` 事件，若存在新 commit 也会触发 `commit.add` 事件
branch.delete	分支删除时触发	流水线配置可挂靠在分支名或 `$` 上，流水线会使用默认分支的配置文件（因为运行时分支已删除）

branch.delete 示例：

.cnb.yml
dev/1:
  branch.delete:
    - stages:
        - name: echo
          # CNB_BRANCH 值为删除的分支
          script: echo $CNB_BRANCH
$:
  branch.delete:
    - stages:
        - name: echo
          # CNB_BRANCH 值为删除的分支
          script: echo $CNB_BRANCH

Pull Request 事件

由 Pull Request（以下简称 PR）相关操作触发的事件。

事件名	触发时机
pull_request	PR 创建、重新打开、源分支 push
pull_request.update	PR 创建、重新打开、源分支 push、PR 的 title 或 description 修改
pull_request.target	PR 创建、重新打开、源分支 push
pull_request.mergeable	开启中的 PR 满足特定条件时触发
pull_request.merged	PR 合并完成时触发
pull_request.approved	用户评审 PR「允许合并」时触发
pull_request.changes_requested	用户评审 PR「需要改进」时触发
pull_request.comment	PR 评论创建时触发

pull_request 与 pull_request.update 的区别

pull_request 是 pull_request.update 的子集：

PR 的 title、description 修改 → 触发 pull_request.update，但不触发 pull_request
PR 创建、重新打开、源分支 push → 同时触发 pull_request 和 pull_request.update

pull_request 与 pull_request.target 的区别

详细区别请参考代码版本选择。

pull_request.mergeable 触发条件

开启中的 PR 同时满足以下条件时触发：

目标分支为 保护分支，并勾选以下规则：
- 需要评审人批准
- 需要通过状态检查（可选）
可合并：
- 无代码冲突
- 状态检查通过（如勾选需要通过状态检查，且有状态检查）
评审通过

pull_request.mergeable 注意事项

配置文件取自目标分支，参考代码版本选择
PR 的目标分支配置了该事件流水线，触发该事件时才会有对应流水线执行

pull_request.merged 注意事项

a 分支合并到 b 分支，会触发 b 分支下的 pull_request.merged、push 事件。

pull_request.approved 注意事项

可能设置里保护分支需要多个评审人批准，有用户通过评审不代表 PR 是评审通过状态。

Tag 事件

由远端代码和页面 Tag 相关操作触发的事件。

事件名	触发时机	说明
tag_push	Tag push 时触发	用于 Tag 推送后的自动化处理
auto_tag	自动生成 Tag 时触发	仅支持在仓库的 Tag 列表页面点击「自动生成 Tag」按钮触发
tag_deploy.*	在仓库 Tag/Release 页面通过「部署」按钮触发	详情参考部署

tag_push 示例：

.cnb.yml
# 对指定 tag 生效
v1.0.*:
  tag_push:
    - stages:
        - name: echo tag name
          script: echo  $CNB_BRANCH

# 对所有 tag 生效
$:
  tag_push:
    - stages:
        - name: echo tag name
          script: echo  $CNB_BRANCH

auto_tag 自动生成 Tag

触发方式：仅支持在仓库的 Tag 列表页面，点击「自动生成 Tag」按钮触发。

实现原理：启动一个流水线，默认使用 cnbcool/git-auto-tag 插件实现自动生成 Tag。

Tag 格式说明：

默认格式为 3.8.11 类型
如果最新一个 Tag 以 v 开头，则自动生成的 Tag 也会带上 v，如 v4.1.9

自定义配置：

.cnb.yml
main: # 默认分支，可使用仓库实际默认分支代替
  auto_tag:
    - stages:
        - name: release rules
          # 该环境变量在触发构建时传入，可查看打印内容看 release 规则
          script: echo -e "$RELEASE_RULES"
        - name: auto tag
          image: cnbcool/git-auto-tag:latest
          settings:
            tagFormat: 'v\${version}'
            branch: $CNB_BRANCH
            repoUrlHttps: $CNB_REPO_URL_HTTPS
            releaseRules: $RELEASE_RULES
          exports:
            tag: NEW_TAG
    - name: show tag
      script: echo $NEW_TAG

配置覆盖规则

默认配置会与 .cnb.yml 合并，同分支名下后者的配置会覆盖前者。如果 .cnb.yml 中 auto_tag 配置在 $ 下而不是默认分支名下，两边的 auto_tag 配置都会保留，但 $ 下的配置会被忽略。参考 include 合并规则。

页面操作事件

web_trigger 自定义事件

事件名格式：web_trigger 或 web_trigger_ 开头，如 web_trigger_test。

触发方式：仅支持在页面触发事件。

使用场景：

场景	说明
部署能力	结合部署能力使用
自定义按钮	页面中的自定义按钮
手动触发构建	支持输入环境变量（仅支持触发 `web_trigger` 事件）

云原生开发事件

在页面点击「云原生开发」按钮触发的事件。详情参考云原生开发。

API 请求事件

api_trigger 自定义事件

事件名格式：api_trigger 或以 api_trigger_ 开头，如 api_trigger_test。

触发方式：

触发来源	说明
cnb:apply	参考 cnb:apply
cnb:trigger	参考 cnb:trigger
OPENAPI	参考 OPENAPI

提示

方式 1 和 2 是对方式 3 的封装。

定时任务事件

由定时任务触发的事件。详情参考定时任务。

Issue 事件

由 Issue 的相关操作触发的事件。

配置要求

Issue 事件流水线配置需挂靠在 $ 下。

事件名	触发时机
issue.open	Issue 创建时
issue.close	Issue 关闭时
issue.reopen	Issue 重新打开时
issue.update	Issue 名称、描述、处理人、标签、优先级变更时
issue.update.assignee_change	Issue 处理人变更时
issue.update.priority_change	Issue 优先级变更时
issue.update.label_change	Issue 标签变更时
issue.comment	Issue 评论时

NPC 事件

在以下场景中于描述或评论中提及 NPC 角色（如 @npc），将触发 NPC 事件：

场景	触发事件
创建 Issue 的描述	`issue.comment@npc`
Issue 评论	`issue.comment@npc`
创建 PR 的描述	`pull_request.comment@npc`
PR 评审	`pull_request.comment@npc`
PR 评论	`pull_request.comment@npc`
PR 评审评论	`pull_request.comment@npc`

更多信息参考 NPC 文档

代码版本选择

事件触发时需要确定对应的代码版本，获取、解析对应的 .cnb.yml，checkout 代码执行流水线。

版本选择策略

事件类型	代码版本选择
push、commit.add、branch.create、vscode	当前分支最新 Commit
auto_tag、branch.delete、issue.*	默认分支最新 Commit
tag_push、tag_deploy.*	当前 Tag
pull_request、pull_request.update、pull_request.approved、pull_request.changes_requested、pull_request.comment	预合并后的 Commit
pull_request.comment@npc	源分支最新 Commit（NPC 在源分支上运行，跨仓 PR 使用源仓库代码）
issue.comment@npc	默认分支最新 Commit
pull_request.merged	合并后的 Commit
pull_request.target、pull_request.mergeable	合并前目标分支最新 Commit
api_trigger	可指定版本；cnb:apply 限制为当前构建的 Commit
web_trigger	从对应分支、Tag 读取配置文件，参考具体应用场景
定时任务	指定分支的最新 Commit
重新构建	当前构建的 Commit

不可信事件

不可信事件是指代码来源或触发者不可控的事件类型。

事件列表

以下事件为不可信事件：

Pull Request 相关事件：

pull_request：PR 创建或源分支 push
pull_request.update：PR 内容更新（含 title、description 修改）
pull_request.approved：PR 审批通过
pull_request.changes_requested：PR 审批被拒绝
pull_request.comment：PR 评论
pull_request.comment@npc：PR 的描述或评论中 @npc 时触发

Issue 相关事件：

issue.comment：Issue 评论
issue.comment@npc：Issue 的描述或评论中 @npc 时触发

风险场景

PR 类事件：

流水线配置源自源分支，可能被未授权用户修改，存在以下风险：

恶意代码注入或敏感内容泄漏
构建产物（如镜像、二进制文件）被篡改
引用密钥仓库文件导致密钥或凭证泄漏

评论类事件：

触发者为评论者，可能非仓库成员或管理员：

访问评论者资源导致数据泄漏
篡改评论者资源造成破坏

NPC 事件：

流水线可由 NPC 所属仓库提供，且触发者为评论者，风险叠加：

NPC 配置来源不可控，可能被恶意篡改
评论者资源泄漏和篡改风险同时存在

安全措施

为降低上述风险，系统对不可信事件采取以下防护措施：

安全措施	说明
CNB_TOKEN 权限限制	流水线环境变量中内置的 CNB_TOKEN 权限受到严格限制，防止越权访问
文件引用显式声明	不可信事件的流水线引用外部文件时，被引用文件必须通过 `allow_events` 显式声明允许被哪些事件引用，避免敏感文件被意外引用

使用建议

安全建议

选择可信 NPC：评论时优先选择可信仓库提供的 NPC 角色
敏感任务隔离：涉及密钥操作、敏感数据处理等重要内容的任务，建议在 push、pull_request.target、tag_push 等可信事件中执行