CNB 文档

简体中文

English

简体中文

English

外观

触发规则

复制页面

3930 字约 13 分钟

当 云原生构建 接收到各类事件时，会自动从仓库对应分支获取 .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

匹配策略

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

优先级匹配阶段说明
1glob 模式匹配尝试用所有 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_requestPR 创建、重新打开、源分支 push
pull_request.updatePR 创建、重新打开、源分支 push、PR 的 title 或 description 修改
pull_request.targetPR 创建、重新打开、源分支 push
pull_request.mergeable开启中的 PR 满足特定条件时触发
pull_request.mergedPR 合并完成时触发
pull_request.approved用户评审 PR「允许合并」时触发
pull_request.changes_requested用户评审 PR「需要改进」时触发
pull_request.commentPR 评论创建时触发

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 同时满足以下条件时触发：

  1. 目标分支为 保护分支，并勾选以下规则：

    • 需要评审人批准
    • 需要通过状态检查（可选）

  2. 可合并：

    • 无代码冲突
    • 状态检查通过（如勾选需要通过状态检查，且有状态检查）

  3. 评审通过

pull_request.mergeable 注意事项

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

pull_request.merged 注意事项

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

pull_request.approved 注意事项

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

Tag 事件

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

事件名触发时机说明
tag_pushTag 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 事件）

AI 相关事件

页面上 AI 相关按钮触发的流水线事件。

事件名触发方式实现原理
ai_issue仓库的 Issue 详情页点击「AI 自动提 PR」按钮启动流水线，借助 AI 根据 Issue 内容自动编码并提交 PR
ai_review仓库的 PR 详情页点击「AI 评审」按钮启动流水线，借助 AI 根据 PR 的 git diff 内容进行代码评审，并提交评审到 PR 评论

ai_review 自定义配置：

可使用默认配置无需自己配置流水线，也可在根目录 .cnb.yml 文件增加配置覆盖默认流水线配置。

下述流水线中使用的镜像插件为 cnbcool/ai-review:latest，可根据需要自定义参数。

.cnb.yml
# $ 表示匹配所有未被其他配置匹配的分支
$:
  ai_review:
    - stages:
        - name: AI code review
          image: cnbcool/ai-review:latest
          settings:
            # 低于 60 分的才发表评论，可根据需要自定义
            score: 60
            # 最大评论数
            max_comments: 5
            # 以下四个参数，可以直接使用点击按钮时传入的环境变量，无需自己配置环境变量
            from: $PULL_REQUEST_FROM # pull_request 源分支
            to: $PULL_REQUEST_TO # pull_request 目标分支
            title: $PULL_REQUEST_TITLE # pull_request 标题
            iid: $PULL_REQUEST_IID # pull_request id

云原生开发事件

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

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.openIssue 创建时
issue.closeIssue 关闭时
issue.reopenIssue 重新打开时
issue.updateIssue 名称、描述、处理人、标签、优先级变更时
issue.update.assignee_changeIssue 处理人变更时
issue.update.priority_changeIssue 优先级变更时
issue.update.label_changeIssue 标签变更时
issue.commentIssue 评论时

NPC 事件

NPC 事件通过 @npc 触发，包含以下场景：

  • 新建 Issue 时的的描述
  • 提交 Issue 评论
  • 新建 Pull Request 时的的描述
  • 提交 Pull Request 的评论，包括普通评论和评审评论

注意

重新打开 PR、Issue，以及编辑描述、评论不会重新触发 NPC 事件。 一次最多支持触发 10 个 NPC 事件。

NPC 角色配置

在 cnb/docs 仓库的 .cnb/settings.yml 文件中，可以定义 NPC 角色。

示例：

.cnb/settings.yml
npc:
  roles:
    - name: 猿芳
      prompt: |
        你用"猿芳"自称，叫用户"大人"，
        你的口头禅是『此事必有蹊跷！』，
        结束对话前礼貌地回复一行："此事背后一定有一个天大的秘密。\n"，
        在最后一行你会输出一张表情包，
        无论是日常对话还是讲解知识，你都会保持以上风格，
        使用中文的『～』代替所有英文的『~』，
        用卑微的语气回答接下来的问题

关于 NPC 的详细配置，请参考 UI 定制配置文件。

触发方式

在 Issue 或 PR 的评论中，通过 @npc 提及 NPC 角色或系统角色即可触发 NPC 事件。

提及 NPC 角色：

@cnb/feedback(猿芳) 帮我回答下这个 issue。

其中，@ 后跟随 NPC 所属的仓库路径 cnb/feedback，括号中为角色名 猿芳。

提及系统角色：

@CodeBuddy 帮我回答下这个 issue。

触发事件列表

触发场景触发事件
Issue 评论中提及 NPCissue.comment@npc
PR 评论中提及 NPCpull_request.comment@npc

执行流程

CNB 会按照以下步骤解析流水线配置：

提及 NPC 角色：

  1. 加载 NPC 所属仓库默认分支（如 main）下的 .cnb.yml 文件
  2. 从配置文件中解析 角色名 对应的事件配置（如 猿芳）
  3. 若未匹配到 角色名 下的事件配置，则解析 $ 下的默认事件配置
  4. 若未解析到事件流水线配置，则使用系统默认的 NPC 事件流水线配置

提及系统角色：

直接使用系统默认的 NPC 事件流水线配置。

NPC 配置示例：

.cnb.yml
.npc: &npc
  - stages:
      - name: echo extra env
        script: |
          echo $CNB_NPC_SLUG
          echo $CNB_NPC_NAME
          echo $CNB_NPC_PROMPT
          echo $CNB_NPC_AVATAR

# NPC 事件可以匹配角色名下的事件
猿芳:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

# 若未在角色名下定义 NPC 事件，则在 $ 下解析
$:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

NPC 流水线配置加载解析完成后会在评论所属仓库的默认分支下执行，触发者为评论者。

安全限制

对于 NPC 事件，流水线环境变量中的 CNB_TOKEN 仅限于访问当前仓库。

环境变量

NPC 事件流水线执行时，会额外增加以下环境变量：

环境变量说明
CNB_NPC_SLUGNPC 所属仓库路径
CNB_NPC_NAMENPC 角色名
CNB_NPC_PROMPTNPC 角色提示词
CNB_NPC_AVATARNPC 头像

关于这些环境变量的具体含义，请参考 默认环境变量。

代码版本选择

事件触发时需要确定对应的代码版本，获取、解析对应的 .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.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 等可信事件中执行
© 2026 cnb.cool