云原生构建

事件

# 事件驱动

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

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

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

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

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

一个操作可以命中多个事件，如创建分支命中 branch.create 和 push，如：

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

配置文件中对应事件流水线会被并行执行。

下面列出了 云原生构建 所支持的事件。

# 云原生开发 事件

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

详情参考云原生开发

# Branch 事件

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

# push

分支 push 时触发。

# branch.create

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

# branch.delete

分支 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 事件

远端代码 Pull Request 相关操作触发的事件 (下文简称 PR)。

# pull_request

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

# pull_request.target

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

# pull_request.mergeable

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

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

# pull_request.merged

PR 合并完成时触发。

提示

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

# pull_request.approved

用户评审 PR 允许合并 时触发。

提示

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

# pull_request.changes_requested

用户评审 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_BRANCH

# auto_tag

自动生成 Tag 事件。

  1. 触发方式

    仅支持在仓库的 Tag 列表页面，点击 自动生成 Tag 按钮触发。

  2. 实现原理

    启动一个流水线，默认使用 cnbcool/git-auto-tag 插件实现自动生成 Tag。

  3. 格式说明

    Tag 默认为 3.8.11 类型的格式。如果最新一个 Tag 以 v 开头，则自动生成的 Tag 也会带上 v，如 v4.1.9。

  4. 自定义 auto_tag 事件流水线

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

    # 用户自定义 .cnb.yml 配置
main: # 默认分支，可使用仓库实际默认分支代替
  auto_tag: # 事件名
    - stages:
        - name: auto 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 页面通过 部署 按钮触发的事件。

详情参考部署

# 自定义 事件

自定义 事件是由 API、定时任务和页面相关操作触发的事件。

# API 自定义事件

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

API 自定义事件有以下三种触发方式：

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

方式 1 和 2 是对方式 3 的封装

# 页面 自定义事件

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

仅支持在页面触发事件。

使用场景：

手动触发构建（支持输入环境变量，仅支持触发 web_trigger 事件）

# 定时任务事件

由定时任务触发的事件。

详情参考定时任务。

# Issue 事件

由 Issue 的相关操作触发的事件。

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

# issue.open

Issue 创建事件。

# issue.close

Issue 关闭事件。

# issue.reopen

Issue 重新打开事件。

# 分支匹配

# 匹配模式

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

.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

# 匹配策略

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

  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. API 自定义事件，可以指定版本，cnb:apply 则限制为当前流水线对应版本。
  8. 页面 自定义事件，会从对应 分支、Tag 读取配置文件，参考具体应用场景。
  9. 定时任务事件，从指定的分支读取配置文件。