触发规则：什么时候跑，跑哪份代码
.cnb.yml 的四层结构里，前两层是"什么时候跑"：分支 + 事件。这两层最容易踩坑，因为它决定了 CNB 去哪读配置、checkout 哪份代码。
一、分支匹配
main: # 精确匹配
"dev/*": # glob：以 dev/ 开头（不跨 /）
"(main|dev)": # main 或 dev
"**/!(main|dev)": # 除 main、dev 外全部分支
$: # 兜底：没被任何 glob 匹配到的分支
匹配分两阶段：先跑所有 glob 规则，都没匹配上才用 $。多条 glob 同时匹配时，各条流水线并发执行。
:::warning 一个高频误解
.cnb.yml 的配置只对当前分支生效。你在 main 里写 dev: 下的流水线，dev 分支 push 时不会按它跑——系统会去读 dev 分支自己的 .cnb.yml。
:::
二、常用事件清单
| 分类 | 事件 | 触发时机 |
|---|---|---|
| 分支 | push | 分支推送 |
| 分支 | commit.add | 推送包含新提交（额外给 CNB_NEW_COMMITS_COUNT） |
| 分支 | branch.create / branch.delete | 分支创建 / 删除 |
| PR | pull_request | PR 创建、重开、源分支 push |
| PR | pull_request.update | 上面这些 + 标题/描述修改 |
| PR | pull_request.target | 同上，但 checkout 目标分支 |
| PR | pull_request.mergeable | 保护分支 + 可合并 + 评审通过 |
| PR | pull_request.merged | PR 合并完成 |
| PR | pull_request.approved / .changes_requested | 评审通过 / 要求修改 |
| PR | pull_request.comment | PR 评论 |
| Tag | tag_push | 推送 Tag |
| 页面 | web_trigger / web_trigger_xxx | 页面按钮手动触发 |
| API | api_trigger / api_trigger_xxx | OpenAPI 或 cnb:trigger 触发 |
| 定时 | crontab: ... | cron 表达式 |
| Issue | issue.open / .close / .comment / .update | Issue 相关操作 |
| NPC | issue.comment@npc / pull_request.comment@npc | 评论里 @NPC |
Issue 类事件有个硬性要求：必须挂在 $ 下。
三、最关键的一张表：跑哪份代码
| 事件 | checkout 的代码 |
|---|---|
push、commit.add、branch.create | 当前分支最新 commit |
issue.*、auto_tag、branch.delete | 默认分支最新 commit |
tag_push | 该 Tag 的 commit |
pull_request 系列 | 预合并后的 commit |
pull_request.target / .mergeable | 目标分支最新 commit |
pull_request.merged | 合并后的 commit |
pull_request.comment@npc | PR 目标分支最新 commit |
issue.comment@npc | 默认分支最新 commit |
api_trigger | 可指定版本 |
"预合并"是什么意思：把源分支合到目标分支上，得到一份临时结果再 checkout。所以你测的是合并后的效果，能提前发现冲突和集成问题。
四、pull_request 和 pull_request.target 怎么选
- 想检查"我这个 PR 合进去会不会炸" → 用
pull_request（预合并） - 想在目标分支状态上跑独立任务（比如打标签、统计） → 用
pull_request.target
五、不可信事件：安全相关的常识
以下事件被归为不可信事件，因为触发者可能没有仓库写权限：
pull_request、pull_request.update、pull_request.approved、pull_request.changes_requested、pull_request.comment、pull_request.comment@npc、所有 issue.* 事件、issue.comment@npc
对它们，平台会自动收窄 CNB_TOKEN：
- 以触发者身份签发，且默认限定在当前仓库
- 引用密钥仓库文件时必须通过
allow_events显式声明允许
所以：涉及密钥、凭据、部署的动作，不要放在 PR/Issue 事件里跑。放在 push、tag_push 这类可信事件里。
六、跳过流水线
三个办法：
# 1. commit message 里标记
git commit -m "docs: 改个说明 [ci skip]"
# 2. push 选项
git push origin main -o ci.skip
第三种是仓库层面的忽略：密钥仓库文件变更、仓库迁移、未勾选「允许自动触发」等，系统本来就不会触发。
前两种只在 push、commit.add、branch.create 上生效。
七、Fork 仓库默认不跑
安全考虑，Fork 出来的仓库在 Git 操作事件、定时任务、Issue 事件下默认不执行流水线。需要在源仓库 设置 → 云原生构建 里勾选允许。
即便允许了，Fork 仓库流水线里的 CNB_TOKEN 也只能访问当前仓库。