云原生构建

事件

# 事件驱动

云原生构建 流水线通过事件触发。以 push 事件为例介绍从代码变更到流水线执行的过程：

  1. 用户提交代码并 push 到远端服务器（CNB）。

  2. 云原生构建 收到 push 事件触发请求，分析出 repository、event、branch 等信息。

  3. 云原生构建 从 repository 仓库 branch 分支获取配置文件(默认 .cnb.yml )，从中解析出 event 对应流水线配置。

  4. 云原生构建 执行流水线。

若命中多个 event，如创建分支命中 branch.create 和 push，配置文件中对应事件会被视作不同 构建 并行执行。

多 event 示例：

dev/1:
  push:
    - stages:
        - name: echo
          script: echo 1
# 匹配所有分支的 branch.create 事件
(**):
  branch.create:
    - stages:
        - name: echo
          script: echo 2

# Git 事件

Git 事件是由远端代码操作触发的事件。

# push

分支 push 事件。

# branch.create

分支创建事件，同时会触发 push 事件。

# 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_BRANCH

# pull_request

分支合并事件，由 PR 的创建、重新打开以及源分支 push 触发。同 pull_request.target 的区别参考配置文件。

示例：pr动态通知到群

# pull_request.target

分支合并事件，由 PR 的创建、重新打开以及源分支 push 触发。同 pull_request 的区别参考配置文件。

# pull_request.approved

分支合并事件，有用户评审 PR 允许合并时触发。

提示

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

# pull_request.changes_requested

分支合并事件，有用户评审 PR 需要改进时触发。

示例：pr动态通知到群

# pull_request.mergeable

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

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

示例：pr动态通知到群

# pull_request.merged

分支合并完成事件。

提示

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

示例：pr动态通知到群

# tag_push

tag push事件。

示例：

v*:
  tag_push:
    - stages:
        - name: echo
          # CNB_BRANCH 值为tag名称
          script: echo $CNB_BRANCH

# vscode

在页面点击 云原生开发 按钮的事件。

参考 云原生开发 自定义创建流程

# auto_tag

自动生成 tag 事件，事件名为 auto_tag。

  1. 触发方式：仅支持在仓库的 tag 列表页面，点击 ”自动生成 Tag“ 按钮触发云原生构建， 借助云原生构建启动一个流水线实现自动生成 Tag， 流水线中使用 cnbcool/git-auto-tag 镜像实现自动生成 Tag。 tag 格式说明：默认为 0.0.1 类似格式。如果最新一个 tag 以 v 开头，则自动生成的 tag 也会带上 v，如 v0.0.1

  2. 如何自定义自动生成 Tag 的流水线

用户可在根目录下增加 .cnb.yml 文件，并增加如下格式配置来覆盖默认模板。

# 用户自定义 .cnb.yml 配置
main: # 默认分支，可使用仓库实际默认分支代替
  auto_tag: # 事件名
    - stages:
        - name: 自动生成 Tag
          image: "cnbcool/git-auto-tag:latest"
          settings:
            tagFormat: 'v\${version}'
            branch: $CNB_BRANCH
            repoUrlHttps: $CNB_REPO_URL_HTTPS
          exports:
            tag: NEW_TAG
        - name: show tag
          script: echo $NEW_TAG

# tag_deploy.*

在仓库 tag/release 页面通过部署按钮触发的事件，详见文档

# Issue 事件

Issue 事件由 issue 的创建、关闭等操作引起的事件。

Issue 事件流水线配置均需挂靠在 $ 下。

# issue.open

issue 创建事件。

示例：issue通知到企业微信群

# issue.close

issue 关闭事件。

# issue.reopen

issue 重新打开事件。

# 自定义事件

事件名为 api_trigger 或者 api_trigger_ 开头，如 api_trigger_test。

自定义事件有以下两种触发方式

  1. 由cnb:apply触发
  2. 由cnb:trigger触发

# web 页面自定义事件

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

仅支持在页面触发事件。

使用场景：

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

# 定时任务事件

由定时任务触发，详情参考定时任务。

# 分支匹配

# glob 模式匹配分支

分支名称支持通过 glob 模式匹配（什么是 glob 匹配？ (opens new window)），如：

# 匹配以 dev/ 开头的所有分支
"dev/*":
  push:
    - push_pipeline

# 匹配 main 或 dev 分支
"(main|dev)":
  push:
    - push_pipeline

# 匹配除 main 和 dev 以外的所有分支
"**/!(main|dev)":
  push:
    - push_pipeline

# 匹配所有分支
"**":
  push:
    - push_pipeline

# 兜底，匹配没有 glob 匹配的分支
"$":
  tag_push:
    - push_pipeline

# 匹配策略

分阶段，按优先级匹配，只有没有匹配结果时，才会尝试下一阶段的匹配。

  1. glob 匹配分支名
  2. $ 兜底匹配所有未被 glob 匹配的分支

如果多个 glob 规则都匹配，所有的被匹配规则会被并行执行。

# 跳过流水线

push 和 branch.create 事件里，以下两种情况会跳过流水线

  1. 最近一个 commit message 里带 [ci skip] 或 [skip ci]
  2. git push -o ci.skip

如：

git commit -m "feat: some feature [ci skip]"
git push origin main

或

git commit -m "feat: some feature"
git push origin main -o ci.skip

# 配置文件版本选择

因为配置文件是在项目仓库中，受到 Git 仓库版本控制的，所以配置文件自然也会有多个版本， 在某次构建中，使用哪个版本的配置文件，应该是开发者必须了解的信息。幸运的是， 云原生构建 的机制是非常符合直觉的，在绝大多数场景下，开发者都不需要额外关心这件事。

下面列举在各个事件中，云原生构建 是如何选择使用哪个配置文件中的内容的，需要额外关注的是 pull_request 事件，它的选择相对复杂一些：

  1. 对于 push、branch.create、vscode 事件，会从当前分支最新 Commit 节点读取配置文件。
  2. 对于 auto_tag、branch.delete、issue.* 会从默认分支读取配置文件。
  3. 对于 tag_push、tag_deploy.* 事件，会从当前 tag 读取配置文件。
  4. 对于 pull_request、pull_request.approved、pull_request.changes_requested 事件，有源分支和目标分支，取预合并后的配置文件。
  5. 对于 pull_request.merged 事件，取合并后的配置文件。
  6. 对于 pull_request.target、pull_request.mergeable 事件，取合并前目标分支的配置文件。
  7. 自定义事件，参考cnb:apply、cnb:trigger。
  8. web 页面自定义事件，会从对应 分支、tag 读取配置文件，参考具体应用场景。
  9. 定时任务事件，从指定的分支读取配置文件。