触发规则

3707 字约 12 分钟

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

触发机制概述

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

Git 操作事件：代码推送、分支创建、PR 操作等
页面操作事件：手动触发、按钮点击、AI 功能操作等
API 请求事件：通过 OPENAPI 或内置任务触发
定时任务事件：按预定时间计划触发
系统事件：Issue 操作、Issue 或 PR 评论等

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

代码示例：

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

触发分支

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

重要提示：在某个分支下配置其他分支的流水线，并不会使其他分支的事件按此配置执行。实际执行取决于各分支自身 .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

匹配策略

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

glob 模式匹配：尝试用所有 glob 规则匹配分支名
兜底匹配：使用 $ 规则匹配所有未被 glob 匹配的分支

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

触发事件

Git 操作事件

Branch 事件

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

push：分支推送时触发。

commit.add：分支推送包含新提交时触发。该事件会多一个环境变量 CNB_NEW_COMMITS_COUNT，值为新增的 Commits 数量。可结合 git log -n 查看新增的 Commits。

branch.create：分支创建时触发，同时会触发 push 事件，若存在新的commit，也会触发 commit.add 事件。

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.target 的区别参考代码版本选择。

pull_request.update：由 PR 的创建、重新打开、源分支 push 以及 PR 的 title、description 修改触发。

注意：pull_request 是 pull_request.update 的子集，即 PR 的 title、description 修改，会触发 pull_request.update 但不触发 pull_request。PR 的创建、重新打开、源分支 push 会同时触发 pull_request 和 pull_request.update。

pull_request.target：由 PR 的创建、重新打开以及源分支 push 触发。同 pull_request 的区别参考代码版本选择。

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

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

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

pull_request.merged：PR 合并完成时触发。

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

pull_request.approved：用户评审 PR 允许合并 时触发。

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

pull_request.changes_requested：用户评审 PR 需要改进 时触发。

pull_request.comment：PR 评论创建时触发。

Tag 事件

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

tag_push：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 文件增加如下配置来覆盖默认模板：

.cnb.yml
# 用户自定义 .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 合并规则合并模式。

tag_deploy.*：在仓库 Tag/Release 页面通过 部署 按钮触发的事件。详情参考部署

页面操作事件

web_trigger 自定义事件

事件名为 web_trigger 或者 web_trigger_ 开头，如 web_trigger_test。

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

使用场景：

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

AI 相关事件

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

ai_issue：根据 Issue 内容，由 AI 自动编码，并提交 PR 到仓库。

触发方式：仅支持在仓库的 Issue 详情页，点击 AI 自动提 PR 按钮触发。
实现原理：启动一个流水线，在流水线中借助 AI 实现根据 issue 内容自动编码并提交 PR。

ai_review：根据 PR 的 git diff 内容，由 AI 进行代码评审，并提交评审到 PR 评论。

触发方式：仅支持在仓库的 PR 详情页，点击 AI 评审 按钮触发。
实现原理：启动一个流水线，在流水线中借助 AI 实现根据 PR 的 git diff 内容，进行代码评审，并提交评审到 PR 评论。
自定义配置：可使用默认配置无需自己配置流水线，也可在根目录 .cnb.yml 文件增加如下配置来覆盖默认流水线配置：

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

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

由 cnb:apply 触发
由 cnb:trigger 触发
由 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 事件

当在 Issue 或 Pull Request (PR) 的评论中提及（@）知识库中的 AI 角色或系统角色 CodeBuddy 时，将触发 NPC 事件。

示例

在 cnb/docs 仓库的 .cnb/settings.yml 文件中，可以定义知识库角色。例如：

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

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

触发方式

在 Issue 或 PR 的评论中，通过 @ 提及知识库角色或系统角色即可触发 NPC 事件。例如：

提及知识库角色：
```
@cnb/docs(猿芳) 帮我回答下这个 issue。
```
其中，@ 后跟随知识库角色所属的仓库路径 cnb/docs，括号中为角色名 猿芳。

提及系统角色：

@CodeBuddy 帮我回答下这个 issue。

触发事件

根据触发场景，将触发以下 NPC 事件：

issue.comment@npc：在 Issue 评论中提及 NPC 时触发。
pull_request.comment@npc：在 PR 评论中提及 NPC 时触发。

执行流程

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

提及知识库角色：
1. 加载知识库角色所属仓库默认分支（如 main）下的 .cnb.yml 文件。
2. 从配置文件中解析 角色名 对应的事件配置（如 猿芳）。
3. 若未匹配到 角色名 下的事件配置，则解析 $ 下的默认事件配置。
4. 若未解析到事件流水线配置，则使用系统默认的 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
          echo $CNB_NPC_ENABLE_THINKING
# NPC 事件可以匹配角色名下的事件
猿芳:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc
# 若未在角色名下定义 NPC 事件，则在 $ 下解析。
$:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

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

环境变量

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

CNB_NPC_SLUG
CNB_NPC_NAME
CNB_NPC_PROMPT
CNB_NPC_AVATAR
CNB_NPC_ENABLE_THINKING

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

代码版本选择

事件触发时需要确定对应的代码版本，获取、解析对应的 .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