触发规则
2349 字约 8 分钟
当 云原生构建 接收到各类事件时,会自动从对应分支获取 .cnb.yml 配置文件,解析出该分支下对应事件的流水线配置,并分配 Runner 执行构建任务。
触发机制概述
云原生构建 支持多种事件触发方式,主要包括:
- Git 操作事件:代码推送、分支创建、PR 操作等
- 页面操作事件:手动触发、按钮点击、AI 功能操作等
- API 请求事件:通过 OPENAPI 或内置任务触发
- 定时任务事件:按预定时间计划触发
- 系统事件:Issue 操作、Issue 或 PR 评论等
以 main 分支代码 push 事件为例,触发流程如下:
代码示例:
main: # 触发分支
push: # 触发事件,对应一个构建,可以包含多条 Pipeline。即可以是数组,也可以是对象。
- stages: # 流水线 1
- echo "do some job"
- stages: # 流水线 2
- echo "do some job"触发分支
触发分支指代码仓库中触发事件的分支,用于匹配对应的流水线配置。
重要提示:在某个分支下配置其他分支的流水线,并不会使其他分支的事件按此配置执行。实际执行取决于各分支自身 .cnb.yml 文件的配置。
匹配模式
分支名称支持 glob 模式匹配(了解 glob 匹配),例如:
.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 数量,最大为 99。可结合 git log -n 查看新增的 Commits。
branch.create:分支创建时触发,同时会触发 push 事件,若存在新的commit,也会触发 commit.add 事件。
branch.delete:分支删除时触发。流水线配置可以挂靠在 分支名 或 $ 上。流水线会使用 默认分支 的配置文件(原因:流水线运行时分支已删除)。
示例:
dev/1:
branch.delete:
- stages:
- name: echo
# CNB_BRANCH 值为删除的分支
script: echo $CNB_BRANCH
$:
branch.delete:
- stages:
- name: echo
# CNB_BRANCH 值为删除的分支
script: echo $CNB_BRANCHPull 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 时触发。
示例:
# 对指定 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_BRANCHauto_tag:自动生成 Tag 事件。
- 触发方式:仅支持在仓库的 Tag 列表页面,点击
自动生成 Tag按钮触发。 - 实现原理:启动一个流水线,默认使用 cnbcool/git-auto-tag 插件实现自动生成 Tag。
- 格式说明:Tag 默认为
3.8.11类型的格式。如果最新一个 Tag 以v开头,则自动生成的 Tag 也会带上v,如v4.1.9。 - 自定义配置:用户可在根目录
.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。
触发方式:仅支持在页面触发事件。
使用场景:
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 评论。
云原生开发事件
在页面点击 云原生开发 按钮触发的事件。详情参考云原生开发
API 请求事件
api_trigger 自定义事件
事件名为 api_trigger 或者以 api_trigger_ 开头,如 api_trigger_test。
触发方式:
- 由 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 评论触发的事件。
代码版本选择
事件触发时需要确定对应的代码版本,获取、解析对应的 .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
