触发规则

3700 字约 12 分钟

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

触发机制概述

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

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

触发流程示例

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

代码示例：

.cnb.yml
main:
  push:
    - stages: # 同一个任务内可定义多个 stage，按顺序串行执行
        - name: job 1
          script: echo "do some job"
        - name: job 2
          script: echo "do some job"

Fork 仓库触发限制

Fork 后的仓库在以下事件中默认不执行流水线：

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

启用 Fork 仓库自动触发

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

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

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

触发分支

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

重要提示

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

匹配模式

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

glob 匹配规则

* 匹配任意字符，但不匹配 /。例如 dev/* 可匹配 dev/feature 但不能匹配 dev/team/feature。
** 匹配任意字符，包括 /。例如 dev/** 可匹配 dev/feature 和 dev/team/feature。

如果分支名包含多级 /，请使用 **。

常用匹配规则

以下分别展示四种常用匹配模式，各模式可组合在同一 .cnb.yml 中：

匹配以 dev/ 开头的分支：

.cnb.yml
"dev/*":
  push:
    - stages:
        - name: do something
          script: echo "dev branch"

匹配 main 或 dev 分支：

.cnb.yml
"(main|dev)":
  push:
    - stages:
        - name: do something
          script: echo "main or dev"

排除 main 和 dev：

.cnb.yml
"**/!(main|dev)":
  push:
    - stages:
        - name: do something
          script: echo "not main or dev"

匹配所有分支（含兜底 $）：

.cnb.yml
"**":
  push:
    - stages:
        - name: do something
          script: echo "all branches"
$:
  push:
    - stages:
        - name: do something
          script: echo "fallback"

模式	匹配范围
`dev/*`	以 `dev/` 开头的分支（不含多级 `/`）
`(main\|dev)`	`main` 或 `dev` 分支
`**/!(main\|dev)`	除 `main` 和 `dev` 外的所有分支
`**`	所有分支
`$`	兜底匹配，不被 glob 匹配的分支

匹配策略

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

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

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

触发事件

Git 操作事件

Branch 事件

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

事件名	触发时机	说明
push	分支推送时触发	最常用的触发事件
commit.add	分支推送包含新提交时	额外提供 `CNB_NEW_COMMITS_COUNT`
branch.create	分支创建时触发	同时触发 `push`；有新 commit 时也触发 `commit.add`
branch.delete	分支删除时触发	使用默认分支的最新代码和配置

branch 事件补充说明：

commit.add：提供 CNB_NEW_COMMITS_COUNT（新增 Commit 数），可结合 git log -n 查看新增 Commit
branch.create：创建分支时会同时触发 push 事件；若推送包含新 commit，也会触发 commit.add 事件
branch.delete：流水线使用默认分支的最新代码版本和配置文件（因为运行时分支已被删除）

branch.delete 与 tag_push 匹配规则一致：均支持精确名称、glob 模式和 $ 兜底匹配。 branch.delete 的示例如下，Tag 事件（tag_push）的示例见下文 Tag 事件。

.cnb.yml
# 精确匹配
main:
  branch.delete:
    - stages:
        - name: echo
          script: echo $CNB_BRANCH
# 兜底匹配
$:
  branch.delete:
    - stages:
        - name: echo
          script: echo $CNB_BRANCH

Pull Request 事件

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

事件名	触发时机
pull_request	PR 创建、重新打开、源分支 push
pull_request.update	PR 创建、重新打开、源分支 push、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.update 补充说明：在 pull_request 的基础上， PR 的 title 或 description 修改也会触发该事件。

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 的目标分支配置了该事件流水线，触发该事件时才会有对应流水线执行
CI 文件解析失败时，若目标分支是保护分支且开启了状态检查，会自动上报失败状态阻止合并；非保护分支不上报

pull_request.merged 注意事项

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

pull_request.approved 注意事项

保护分支可能设置了多个评审人批准的要求，仅有一位用户通过评审不代表 PR 已处于评审通过状态。

Tag 事件

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

事件名	触发时机	说明
tag_push	Tag push 时触发	用于 Tag 推送后的自动化处理
auto_tag	自动生成 Tag 时触发	见下方「auto_tag 自动生成 Tag」说明
tag_deploy.*	通过「部署」按钮触发	详情参考部署

tag_push：Tag 推送时触发，支持精确 Tag 名、glob 模式和 $ 兜底匹配。配置结构如下：

.cnb.yml
# 精确匹配
v1.0.0:
  tag_push:
    - stages:
        - name: echo
          script: echo $CNB_BRANCH
# glob 模式匹配
v*:
  tag_push:
    - stages:
        - name: echo
          script: echo $CNB_BRANCH
# 兜底匹配
$:
  tag_push:
    - stages:
        - name: echo
          script: echo $CNB_BRANCH

auto_tag 自动生成 Tag

触发方式：仅支持在仓库的 Tag 列表页面，点击「自动生成 Tag」按钮触发。按钮会以 tag.auto_tag.branch 指定的分支（默认仓库默认分支）启动流水线，该分支可通过 Tag 自动生成配置在 .cnb/settings.yml 中配置。

实现原理：启动一个流水线，默认使用 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
          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
        # exports 的生命周期为当前 Pipeline，需在同一 Pipeline 的后续 stage 中使用
        - 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` 事件）

触发来源	说明
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.update.assignee_change	Issue 处理人变更时
issue.update.priority_change	Issue 优先级变更时
issue.update.label_change	Issue 标签变更时
issue.comment	Issue 评论时

以下示例将 issue.open、issue.comment 流水线挂靠在 $ 下，分别在 Issue 创建、评论时执行任务：

.cnb.yml
$:
  issue.open:
    - stages:
        - name: notice issue
          script: echo "$CNB_ISSUE_TITLE" opened
  issue.comment:
    - stages:
        - name: notice issue
          script: echo "$CNB_ISSUE_TITLE" commented

其余事件（如 issue.close、issue.update 等）写法相同，仅需替换事件名。更完整的通知示例（如 Issue 变更时推送企业微信群）参考 Issue 通知示例。

评论数限制

当 Issue 或 PR 的评论数超过 100 条时，对应的 issue.comment / pull_request.comment 及 @npc 事件均不再触发流水线。

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	预合并后的 Commit
pull_request.update	预合并后的 Commit
pull_request.approved	预合并后的 Commit
pull_request.changes_requested	预合并后的 Commit
pull_request.comment	预合并后的 Commit（见说明 3）
pull_request.comment@npc	目标分支最新 Commit（见说明 4）
issue.comment@npc	默认分支最新 Commit
pull_request.merged	合并后的 Commit
pull_request.target、pull_request.mergeable	合并前目标分支最新 Commit
api_trigger	可指定版本（见说明 1）
web_trigger	从对应分支或 Tag 读取配置（见说明 2）
定时任务	指定分支的最新 Commit
重新构建	当前构建的 Commit

补充说明：

api_trigger：可指定版本；cnb:apply 限制为当前构建的 Commit
web_trigger：从对应分支、Tag 读取配置文件，参考具体应用场景
pull_request.comment：PR 已合并时使用合并后的 Commit（源分支可能已删除，不做预合并）
pull_request.comment@npc：
- 跨仓 Fork PR 且触发者为 PR 提交者：使用源仓库源分支代码
- PR 已合并：使用合并后的 Commit（源分支可能已删除），可配合 git cherry-pick 把提交同步到其他分支

不可信事件

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

事件列表

以下事件为不可信事件：

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.open：Issue 创建
issue.reopen：Issue 重新打开
issue.close：Issue 关闭
issue.update：Issue 内容更新（含 title、description 修改）
issue.update.assignee_change：Issue 处理人变更
issue.update.priority_change：Issue 优先级变更
issue.update.label_change：Issue 标签变更
issue.comment：Issue 评论
issue.comment@npc：Issue 的描述或评论中 @npc 时触发

风险场景

PR 类事件：

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

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

Issue、评论类事件：

Issue 的创建、关闭/重新打开、编辑与评论均无需仓库写权限，触发者可能非仓库成员或管理员：

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

NPC 事件：

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

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

安全措施

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

CNB_TOKEN 权限限制：流水线环境变量中内置的 CNB_TOKEN 权限受到严格限制，防止越权访问
CNB_TOKEN 角色封顶：非 NPC 的不可信事件下，CNB_TOKEN 的最大角色固定为 Reporter（助手），触发者角色更高时同样按助手计算
文件引用显式声明：不可信事件的流水线引用外部文件时，被引用文件必须通过 allow_events 显式声明允许被哪些事件引用，避免敏感文件被意外引用

使用建议

安全建议

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