腾讯云 CNB 触发规则全解析：push、PR、定时、手动事件一次讲清

原创

克劳德2048

发布于 2026-08-24 15:15:04

490

摘要：

腾讯云云原生构建（CNB）支持 push、pull_request、crontab、web_trigger 等多种触发事件，本文详解各类事件的配置语法与实战示例，帮助开发者快速掌握 .cnb.yml 触发规则的使用方法。

一、触发规则核心概念

腾讯云云原生构建（CNB）是腾讯云推出的 AI Native Git 平台，通过 .cnb.yml 配置文件实现声明式流水线编排。触发规则是流水线的"启动开关"，决定了流水线在什么条件下自动或手动执行。

CNB 支持六大类触发事件，覆盖研发全流程：

事件类型	触发场景	典型用途
Git 操作事件	代码推送、分支创建、PR 操作	提交后自动构建、代码审查
页面操作事件	手动点击按钮、云原生开发	生产发布、临时构建
API 请求事件	通过 OpenAPI 或内置任务调用	跨系统集成、自动化编排
定时任务事件	按 cron 表达式周期性触发	夜间构建、定期测试
Issue 事件	Issue 创建、更新、评论	自动化通知、状态同步
NPC 事件	描述或评论中 @npc	AI 自动回复、智能编码

触发流程：当 CNB 接收到上述事件时，自动从仓库对应分支获取 .cnb.yml，解析该分支下对应事件的流水线配置，并分配构建节点执行。

二、Git 操作事件配置详解

Git 操作事件是日常开发中使用频率较高的触发方式，包括分支事件和 Pull Request 事件两大类。

2.1 分支事件

分支事件由远端代码分支变动触发，主要包含以下类型：

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

push 事件配置示例：

main:
  push:
    - stages:
        - name: install
          image: node:20
          script: npm install
        - name: test
          image: node:20
          script: npm test
        - name: build
          image: node:20
          script: npm run build

branch.delete 事件配置示例：

main:
  branch.delete:
    - stages:
        - name: cleanup
          script: echo "Branch $CNB_BRANCH was deleted"

2.2 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 事件配置示例：

main:
  pull_request:
    - lock:
        key: pr
        cancel-in-progress: true
      stages:
        - name: lint
          image: node:20
          script: npm run lint
        - name: test
          image: node:20
          script: npm run test

2.3 分支匹配规则

分支名称支持 glob 模式匹配，可为不同分支配置不同的构建流程：

匹配模式	匹配范围	示例
`dev/*`	以 dev/ 开头的分支（不含多级 /）	dev/feature、dev/bugfix
`(main\\|dev)`	main 或 dev 分支	main、dev
`**/!(main\\|dev)`	除 main 和 dev 外的所有分支	feature/xxx、hotfix/xxx
`**`	所有分支	任意分支名
`$`	兜底匹配，不被 glob 匹配的分支	特殊用途

多分支匹配配置示例：

# 匹配以 dev/ 开头的分支
"dev/*":
  push:
    - stages:
        - name: dev-build
          script: echo "Development branch build"

# 匹配 main 或 dev 分支
"(main|dev)":
  push:
    - stages:
        - name: main-build
          script: echo "Main branch build"

# 匹配所有分支
"**":
  push:
    - stages:
        - name: all-branch-build
          script: echo "All branches build"

三、定时任务与手动触发配置

3.1 定时任务（crontab）

定时任务适用于夜间构建、定期测试、数据备份等周期性场景。通过 cron 表达式定义触发计划，配置须以 crontab: 为前缀。

定时任务配置示例：

main:
  "crontab: 30 5,17 * * *":
    - name: nightly-build-and-test
      stages:
        - name: run-tests
          script: echo "Running scheduled tasks..."
        - name: build-docker
          script: docker build -t my-image .

上述配置表示每天在系统时区（Asia/Shanghai）的 5:30 AM 和 5:30 PM 各触发一次。

定时任务关键特性：

特性	说明
分支配置	仅支持单一明确分支，不支持 glob 表达式
最小间隔	5 分钟（低于此间隔无法提交）
执行身份	最后添加或修改配置的用户
删除方式	从配置中移除 crontab 条目即可

3.2 手动触发（web_trigger）

手动触发适用于生产发布、临时构建等需要人工介入的场景。通过在仓库根目录创建 .cnb/web_trigger.yml 文件配置自定义按钮。

基础按钮配置示例：

# .cnb/web_trigger.yml
branch:
  - reg: ^release
    buttons:
      - name: 发布构建
        description: 触发生产环境构建
        event: web_trigger_release

带环境变量输入的按钮配置：

# .cnb/web_trigger.yml
branch:
  - reg: ^release
    buttons:
      - name: 发布
        event: web_trigger_release
        inputs:
          version:
            name: 版本号
            type: input
            required: true
            default: "1.0.0"
          environment:
            name: 目标环境
            type: select
            default: staging
            options:
              - name: 开发环境
                value: dev
              - name: 预发布环境
                value: staging
              - name: 生产环境
                value: production

对应的 .cnb.yml 流水线配置：

# .cnb.yml
release*:
  web_trigger_release:
    - stages:
        - name: 输出版本信息
          script:
            - echo "Version: $version"
            - echo "Environment: $environment"
        - name: 执行构建
          script: |
            npm install
            npm run build
            npm run deploy -- --env=$environment

输入类型支持：web_trigger 支持八种输入类型：input、textarea、select、switch、radio、date、datetime、daterange，满足不同参数输入需求。

四、高级触发场景

4.1 Issue 事件

Issue 事件由 Issue 相关操作触发，可实现自动化通知和状态同步。配置需挂靠在 $ 下：

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

Issue 事件配置示例：

$:
  issue.open:
    - stages:
        - name: notify-team
          script: echo "New issue created: $CNB_ISSUE_TITLE"

  issue.comment:
    - stages:
        - name: process-comment
          script: echo "New comment on issue $CNB_ISSUE_IID"

4.2 NPC 事件

NPC（Non-Player Character）是 CNB 的 AI 角色功能，在描述或评论中 @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

需要留意的是，当 Issue 或 PR 的评论数超过 100 条时，对应的 issue.comment / pull_request.comment 及 @npc 事件均不再触发流水线；此外一次最多支持触发 10 个 NPC 事件。配置自动化回复时，应将这些约束纳入考量，避免因评论数超限导致预期内的 NPC 响应失效。

另外，并非所有位置的 @ 提及都会触发 NPC 事件——引用（blockquote）、代码块（code）、折叠块（details）、有序列表、无序列表、表格以及部分 HTML 标签中的 @ 提及均不会被识别为触发指令。因此建议将 @npc 写在正文的普通段落中，避免因排版格式导致触发失效。

4.3 API 触发

通过 OpenAPI 或内置任务触发流水线，适用于跨系统集成场景：

触发方式	说明
cnb:apply	内置任务触发
cnb:trigger	内置任务触发
OpenAPI	通过 API 接口调用

五、触发成本说明

触发流水线会消耗构建资源，消耗多少取决于该分支匹配到的节点规格与运行时长。CNB 社区版每月提供云原生构建 CPU 160 核时的免费额度，月底清零、不叠加至次月。合理设计触发规则——例如仅在 PR 创建时跑 lint、只在合并到主干时才构建镜像——可以有效控制免费额度的使用节奏，避免不必要的资源消耗。

六、总结

腾讯云云原生构建（CNB）提供了完善的触发规则体系，覆盖从代码提交到生产发布的全流程自动化需求。通过灵活的 glob 分支匹配、细粒度的 PR 事件、可定制的定时任务和手动触发按钮，开发者可以根据实际场景选择最合适的触发方式。

结合免费额度 + 超额按量计费的计费模式，CNB 既能满足个人开发者和开源项目的日常使用，也能支撑企业级大规模构建需求。

想在自己的仓库里把 push、PR、定时、手动这些触发规则配起来，可以到腾讯云 CNB 新建一条流水线，用一份 .cnb.yml 就能跑通第一套自动化触发。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

配置