内置任务

在每一阶段(Stage)操作中,除了使用自定义任务, CNB 还扩展了一些常用的内置任务,以供开发者使用。

Docker

cache

docker:cache

==Docker 缓存==,构建一个 Docker 镜像作为缓存,在未来的构建中重复使用。

可以避免网络资源如 依赖包 重复下载。

适用事件

所有事件

参数

dockerfile

用于构建缓存镜像的 Dockerfile 路径。

为避免超长时间构建,Docker 镜像构建超时时间受 job.timeout 参数控制。

by

用来声明缓存镜像构建过程中依赖的文件列表。注意:未出现在 by 列表中的文件,除了 Dockerfile,其他在构建镜像过程中,都当不存在处理。

versionBy

用来进行版本控制,未传入 versionBy,则默认取 by 的值进行版本控制。

versionBy 所指向的文件内容发生变化,我们就会认为是一个新的版本, 具体的计算逻辑见这个表达式:sha1(Dockerfile + versionBy + buildArgs + target + arch)。

buildArgs

在 build 时插入额外的构建参数 (--build-arg $key=$value), value 值为 null 时只加入 key (--build-arg $key)。

target

对应 docker build 中的 –target 参数,可以选择性地构建 Dockerfile 中的特定阶段,而不是构建整个 Dockerfile。

sync

是否同步模式,等待缓存镜像 docker push 成功后才继续。

ignoreBuildArgsInVersion

版本计算是否忽略 buildArgs。

详见版本控制

输出结果

1{
2  // 缓存对应的 docker image name
3  name;
4}

配置样例

 1main:
 2  push:
 3    - docker:
 4        image: node:14
 5      stages:
 6        - name: build cache image
 7          type: docker:cache
 8          options:
 9            dockerfile: cache.dockerfile
10            # by 支持以下两种形式:数组、字符串
11            by:
12              - package.json
13              - package-lock.json
14            # versionBy: package-lock.json
15            versionBy:
16              - package-lock.json
17          exports:
18            name: DOCKER_CACHE_IMAGE_NAME
19        - name: use cache
20          image: $DOCKER_CACHE_IMAGE_NAME
21          # 将 cache 中的文件拷贝过来使用
22          commands:
23            - cp -r "$NODE_PATH" ./node_modules
24        - name: build with cache
25          script:
26            - npm run build

其中,cache.dockerfile 是一个用于构建缓存镜像的 Dockerfile。示例:

 1# 选择一个 Base 镜像
 2FROM node:14
 3
 4# 设置工作目录
 5WORKDIR /space
 6
 7# 将 by 中的文件列表 COPY 过来
 8COPY . .
 9
10# 根据 COPY 过来的文件进行依赖的安装
11RUN npm ci
12
13# 设置好需要的环境变量
14ENV NODE_PATH=/space/node_modules

cnb

await

参见 await-resolve

resolve

参见 await-resolve

await-resolve

await 会等待 resolve 的执行,resolve 可以向 await传递变量。

通过 await-resolve,可以让多个并发的 pipeline 相互配合,实现更灵活的顺序控制。

:::tip

await-resolve 同 apply、trigger 的区别:

前者指一个构建中某 pipeline 执行到 await 任务时等待对应 key 的 resolve 通知才会继续进行。

后者指一个 pipeline 触发新事件,开启新的构建。可以跨仓库。可以异步调用,也可以同步等待。 :::

使用限制

  1. 只能对同一个事件触发的 pipeline 进行 await 和 resolve 操作
  2. 一个 key 仅能 resolve 一次,但可以 await 多次
  3. 通过 key 对 await 和 resolve 进行分组

死锁检测

await 和 resolve 相互配合可以完成灵活的流程控制,但也会引入更复杂的边界情况,比如:

  1. pipeline-1 和 pipeline-2 相互 await,即:死锁
  2. 多条 pipeline 间存在 await 环,即:间接死锁
  3. await 一个不存在的 key,或者 key 没有关联 resolve,即:无限等待
  4. resolve 所在 pipeline 执行失败,对应的 await 陷入无限等待
  5. 多个 resolve 任务关联同一个 key,即重复 resolve 抛出异常

死锁检测 机制会自动检测以上异常,结束 await 的等待状态,抛出 dead lock found. 异常。

await 和 resolve 的在配置文件中顺序不影响运行结果,即最后 await 任务一定是会等待相应的 resolve 完成,这种情况不会被死锁检测机制终止。

适用事件

所有事件

await 参数

key

配对 ID

resolve 参数
key

配对 ID

data

要传递的对象

key: value 格式,支持多级。示例:

1- name: resolve a json
2  type: cnb:resolve
3  options:
4    key: demo
5    data:
6      a: 1
7      b:
8        c: 2

await 任务的结果,是 resolve 声明的 data 对象。 可以通过 exports 访问这个对象,示例:

 1- name: await a json
 2  type: cnb:await
 3  options:
 4    key: demo
 5  exports:
 6    a: VAR_A
 7    b.c: VAR_B
 8- name: show var
 9  script:
10    - echo ${VAR_A} # 1
11    - echo ${VAR_B} # 2

当然,也可以不传送任务内容,仅仅表示一个等待动作:

1- name: ready
2  type: cnb:resolve
3  options:
4    key: i-am-ready
1- name: ready
2  type: cnb:await
3  options:
4    key: i-am-ready
输出结果
1{
2  // resolve 返回的 data 内容
3  data;
4}

apply

cnb:apply

适用事件

参数

config
configFrom
event
sync

同步模式下会等待本次 apply 流水线执行成功,再执行下一个任务。

continueOnBuildError
title

环境变量相关

当前 Job 可见的,业务定义的环境变量全部传递给新的流水线。

默认值中有如下环境变量,用户无法覆盖:

config 取值优先级

按以下顺序依次取值,取到为止:

  1. config
  2. configFrom
  3. 当前仓库 .cnb.yml
  4. 若在 pull_request.merged 事件中调用 apply 内置任务,取合并后的配置文件
  5. 若在 pull_request.target、pull_request.mergeable 事件中调用 apply 内置任务,取目标分支的配置文件
  6. 其他情况取当前分支配置文件

configFrom 只支持本地文件如 ./test/.cnb.yml,远程文件可先自行下到本地。

输出结果

1{
2  "sn": "cnb-i5o-1ht8e12hi", // 构建号
3  "buildLogUrl": "http://xxx/my-group/my-repo/-/build/logs/cnb-i5o-1ht8e12hi", // 构建日志链接
4  "message": "success",
5  "buildSuccess": true, // 触发的构建是否成功,此key仅在同步模式下存在
6  "lastJobExports": {} // 触发的流水线最后一个job导出的环境变量
7}

配置样例

1main:
2  push:
3    - stages:
4        - name: trigger
5          type: cnb:apply
6          options:
7            configFrom: ./test/.cnb.yml
8            event: api_trigger_test
 1main:
 2  push:
 3    - stages:
 4        - name: trigger
 5          type: cnb:apply
 6          options:
 7            config: |
 8              main:
 9                api_trigger_test: 
10                - stages:
11                  - name: test
12                    script: echo test
13
14            event: api_trigger_test
 1main:
 2  push:
 3    - stages:
 4        - name: trigger
 5          type: cnb:apply
 6          options:
 7            # 执行当前配置文件的其它事件
 8            event: api_trigger_test
 9  api_trigger_test:
10    - stages:
11        - name: test
12          script: echo test
1main:
2  push:
3    - stages:
4        - name: trigger
5          type: cnb:apply
6          options:
7            configFrom: .xxx.yml
8            event: api_trigger_test
9            sync: true

read-file

cnb:read-file

读取文件内容解析输出给后续任务。

用 ##[set-output key=value] 指令输出变量更便捷,但会将内容输出到日志,不适用于敏感信息。

对于事先确定的敏感信息可以用 imports 导入,对于构建过程中生成的敏感信息,可写入文件,用该内置任务读取。

imports 只支持远端仓库存在的文件,该内置任务只支持读取本地存在的文件。

文件类型通过后缀判断,目前支持 json、 yml(yaml)、 纯文本(key=value 结构)。

适用事件

所有事件

参数

filePath

本地文件路径

输出结果

1{
2  // 读到的对象
3}

配置样例

将一些后续任务需要的变量写入文件,用该内置任务读取文件导出为环境变量,供后续任务使用。

1{
2  "myVar": "myVar",
3  "deep": {
4    "myVar": "myVar in deep"
5  },
6  "deepWithEnvKey": {
7    "myVar": "myVar in deepWithEnvKey"
8  }
9}
 1main:
 2  push:
 3    - env:
 4        myKey: deepWithEnvKey
 5      stages:
 6        - name: write env file
 7          script: echo "write env to myJson.json"
 8        - name: export env
 9          type: cnb:read-file
10          options:
11            filePath: myJson.json
12          exports:
13            myVar: ENV_MY_VAR
14            deep.myVar: ENV_DEEP_MY_VAR #指定多级的key
15            $myKey.myVar: ENV_ENV_KEY_MY_VAR #通过环境变量指定获取的key
16        - name: echo env
17          script:
18            - echo $ENV_MY_VAR
19            - echo $ENV_DEEP_MY_VAR
20            - echo $ENV_ENV_KEY_MY_VAR

trigger

cnb:trigger

在当前仓库中,触发另外一个仓库的自定义事件流水线。

适用事件

所有事件

参数

token

个人访问令牌。

新流水线触发者为令牌对应用户,会判断有无目标仓库权限。

slug

目标仓库的完整路径,如:group/repo。

event

触发的自定义事件名,必须是 api_trigger 或以 api_trigger_ 开头。

需要目标仓库配置了对应事件的流水线,才可以触发。

branch

触发分支,默认为主分支。

sha

触发分支中的 CommitId,默认取 branch 的最新提交记录。

env

触发目标仓库流水线时的环境变量。

默认值中有如下环境变量,用户无法覆盖:

sync

是否同步执行,同步模式下会等待本次 trigger 流水线执行成功后,再执行下一个任务。

continueOnBuildError

同步模式下,触发的流水线构建失败时,是否继续执行下个任务。

title

自定义流水线标题

类型定义
TriggerEnv
1{
2    [key: String]: String | Number | Boolean
3}

输出结果

1{
2  "sn": "cnb-i5o-1ht8e12hi", // 构建号
3  "buildLogUrl": "http://xxx/my-group/my-repo/-/build/logs/cnb-i5o-1ht8e12hi", // 构建日志链接
4  "message": "success",
5  "buildSuccess": true, // 触发的构建是否成功,此key仅在同步模式下存在
6  "lastJobExports": {} // 触发的流水线最后一个job导出的环境变量
7}

配置样例

基本使用

在当前仓库触发一个仓库 main 分支的事件名为 api_trigger_test 的流水线。

该流水线配置文件使用仓库 main 分支的 .cnb.yml 文件。

使用访问令牌 $TOKEN 查询用户是否有仓库权限。

 1main:
 2  push:
 3    - stages:
 4        - name: trigger
 5          type: cnb:trigger
 6          imports: https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/envs.yml
 7          options:
 8            token: $TOKEN
 9            slug: a/b
10            branch: main
11            event: api_trigger_test

vscode

go

vscode:go

远程开发中是否配置该内置任务的区别:

上述入口出现时机区别:仅指从 loading 等待页到跳转入口选择页出现的时机。 实际上无论是否使用该任务,在 code-server 代码服务启动后,远程开发已经是可用状态。

注意:使用该任务将增加等待时间。如果需要延迟开发者进入时机,在某些任务执行完才允许进入远程开发环境,可使用该任务。

适用事件

输出结果

1{
2  // webide url
3  "url": ""
4}

配置样例

 1$:
 2  # vscode 事件:专供页面中启动远程开发用
 3  vscode:
 4    - docker:
 5        # 使用自定义镜像作为开发环境,未传入此参数,将使用默认镜像 cnbcool/default-dev-env:latest
 6        image: cnbcool/default-dev-env:latest
 7      services:
 8        - vscode
 9        - docker
10      stages:
11        # 希望等该任务执行完再进入开发环境
12        - name: ls
13          script: ls -al
14        - name: vscode go
15          type: vscode:go
16        # 可以在进入开发环境后再执行的任务
17        - name: ls
18          script: ls -al

git

auto-merge

git:auto-merge

==自动合并 Pull Request==,一般用于 PR 通过 pull_request 流水线检查 和 Code Review 后,在 pull_request.mergeable 流水线中自动合并 PR。无需人工点击合并按钮。

pull_request.mergeable 事件触发条件和时机参考事件。

适用事件

pull_request.mergeable

参数

mergeType
mergeCommitMessage

当合并策略为 rebase 的时候,该信息无效,无需填写。

当合并策略为 merge ,默认为 chore: merge node(merged by CNB) ,会自动追加 PR 引用、reviewers 名单、PR 包含的提交人名单。举例说明:

1chore: merge node(merged by CNB)
2
3PR-URL: !916
4Reviewed-By: tom
5Reviewed-By: jerry
6Co-authored-by: jack

当合并策略为 squash 时,默认值为该 pr 的第一条 commit message。并会自动追加 pr 引用和 reviewers 名单、pr 包含的提交人名单。举例说明:

1main:
2  pull_request.mergeable:
3    - stages:
4        - name: automerge
5          type: git:auto-merge
6          options:
7            mergeType: squash

该配置会产生如下效果:

某个 PR (feat/model-a -> main) 中有两条提交记录:

提交记录 1,2023-10-1 日提交

1feat(model-a): 给模块 A 增加一个新特性
2
3由于某某原因,新增某某特性
4
5close #10

提交记录 2,修复了在 cr 时被指出的一些问题,2023-10-2 日提交

1fix(model-a): 修复评审中指出的问题

在自动合并后将会在 main 分支上产生一个这样的提交节点,即后续的提交记录(也就是提交记录 2)将会被抹掉

 1feat(model-a): 给模块 A 增加一个新特性
 2
 3由于某某原因,新增某某特性
 4
 5close #10
 6
 7PR-URL: !3976
 8Reviewed-By: tom
 9Reviewed-By: jerry
10Co-authored-by: jack
mergeCommitFooter

合并点需要设置的脚注,多个脚注用 \n 分隔,仅在 merge 和 squash 生效。

当合并策略为 rebase 的时候,该信息无效,无需填写。

当合并策略为 merge 或 squash 时,会将传入信息按行加入到脚注中,再追加 PR 引用、reviewers 名单、pr 包含的提交人名单。举例说明:

1main:
2  pull_request.mergeable:
3    - stages:
4        - name: automerge
5          type: git:auto-merge
6          options:
7            mergeType: squash
8            mergeCommitMessage: "add feature for some jobs"
9            mergeCommitFooter: "--story=123\n--story=456"
1add feature for some jobs
2
3--story=123
4--story=456
5PR-URL: !916
6Reviewed-By: tom
7Reviewed-By: jerry
8Co-authored-by: jack
removeSourceBranch

合并后是否删除源分支。

源分支与目标分支不同仓库时,该值无效。

ignoreAssignee

是否忽略 assignee。

当该 PR 有指定 assignee (指派人)的时候,本任务不会执行自动合并的逻辑。 因为 assignee 的本意就是指派某人手动来处理。

当为 true 时,可忽略 assignee 强行合并。

输出结果

1{
2    reviewedBy, // String,追加在提交信息后面的提交者信息
3    reviewers, // Array<String>, 走查者列表
4}

配置样例

单独使用
1main:
2  pull_request.mergeable:
3    - stages:
4        - name: automerge
5          type: git:auto-merge
6          options:
7            mergeType: merge

当分支 main 上 的 PR 触发了 pull_request.mergeable 事件,那么会将这个 PR 以 merge 的方式自动合并。

配合目标分支的 push 事件使用
 1main:
 2  push:
 3    - stages:
 4        - name: build
 5          script: npm run build
 6        - name: publish
 7          script: npm run publish
 8  pull_request.mergeable:
 9    - stages:
10        - name: automerge
11          type: git:auto-merge
12          options:
13            mergeType: merge

当分支 main 上 的 PR 触发了 pull_request.mergeable 事件,那么会将这个 PR 以 merge 的方式自动合并。 在自动合并之后,会触发目标分支(main)上的 push 事件,继续执行声明的 build 和 publish 流程。

这里有一个谁应该对产生的 push 事件流程负责的问题,这里的设定是这样的:

  1. 如果提出 PR 者,是目标仓库的成员,那么提出 PR 的人对后续产生的 push 事件流程负责(即 push 构建流水会推送到这里)。
  2. 如果提出 PR 者,不是目标仓库的成员(比如在开源项目中,从 Forked Repo 提出 PR)。那么最后一个 Code Review 的 Reviewer 将对后续产生的 push 事件流程负责。

最佳实践

使用 squash 自动合并

使用 squash 合并,一次 PR 操作只在目标分支产生一个 commit 节点,并且在有权限的情况下删除源分支。

1main:
2  review:
3    - stages:
4        - name: automerge
5          type: git:auto-merge
6          options:
7            mergeType: squash
8            removeSourceBranch: true
使用 auto 自动选择合并类型

如果多人提交走 merge ,否则走 squash。

1main:
2  review:
3    - stages:
4        - name: automerge
5          type: git:auto-merge
6          options:
7            mergeType: auto
建立专用的 CR 群交叉走查自动合并
  1. 走查通过后自动合并
  2. 记录走查者信息在提交信息中
 1main:
 2  pull_request.mergeable:
 3    - stages:
 4        - name: CR 通过后自动合并
 5          type: git:auto-merge
 6          options:
 7            mergeType: squash
 8            mergeCommitMessage: $CNB_LATEST_COMMIT_MESSAGE
 9          exports:
10            reviewedBy: REVIEWED_BY
11        - name: notify
12          image: tencentcom/wecom-message
13          settings:
14            robot: "155af237-6041-4125-9340-000000000000"
15            msgType: markdown
16            content: |
17              > CR 通过后自动合并 <@${CNB_BUILD_USER}> 
18              >  
19              > ${CNB_PULL_REQUEST_TITLE}
20              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
21              > 
22              > ${REVIEWED_BY}
23
24  pull_request:
25    - stages:
26        # ...省略其它任务
27        - name: notify
28          image: tencentcom/wecom-message
29          options:
30            robot: "155af237-6041-4125-9340-000000000000"
31            msgType: markdown
32            content: |
33              > ${CURR_REVIEWER_FOR_AT}
34              > 
35              > ${CNB_PULL_REQUEST_TITLE}
36              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
37              > 
38              > from ${CNB_BUILD_USER}

issue-update

git:issue-update

==更新 Issue 状态==,关闭或打开 Issue,修改 Issue 标签。

适用事件

所有事件

工作机制

查找 Issue 是否存在 -> 检查是否符合 when 条件(可选) -> 检查是否符合 lint 条件(可选)-> 更新 issue 状态或标签

Issue ID 获取方式

获取方式:提取上述文本中如下两种格式

注意 #123 或 test/test#123 前需要有空格。

提交日志中如何带上 Issue ID

提交代码时,可以在提交日志中加上关联的 Issue ID, 可以在使用当前内置任务时可以自动提取到关联 Issue,用来更新 Issue 标签和状态

推荐在提交日志的 body 中带上 Issue ID,命令行操作方式如下:

1git commit -m "fix(云原生构建): 修复一个错误
2
3cnb/feedback#123"

以下提交方式 title 和 body 之间会产生两个换行

1git commit -m "fix(云原生构建): 修复一个错误" -m "cnb/feedback#123"

参数

fromText

从给定的文本中解析 Issue Id。

不声明时,自动从上下文里的提交记录解析。

可以指定一个包含 issue id 引用的文本来声明操作对象,比如: ${LATEST_CHANGE_LOG} 。

state

对应 state 属性,为 close 时,可关闭 Issue。

label

对 label 的操作描述。

when

过滤条件,多个条件之间是 or 关系。为空时表示对所有 Issue 操作。

lint

检查 Issue 是否满足条件,不满足时抛出异常,多个条件之间是 or 关系,为空时表示不做检查。

defaultColor

添加的标签的默认颜色,当有传入 label.add 参数时才有效。

类型定义
IssueStateMap

open | close

IssueUpdateLabel
IssueUpdateStatus

输出结果

1{
2    issues // issue 列表
3}

配置样例

 1main:
 2  push:
 3    - stages:
 4        - name: update issue
 5          type: git:issue-update
 6          options:
 7            # 移除 “开发中” 标签,添加 “预发布” 标签
 8            label:
 9              add: 预发布
10              remove: 开发中
11            # 当有 “feature” 或 “bug” 标签才进行上述标签操作
12            when:
13              label:
14                - feature
15                - bug
 1$:
 2  tag_push:
 3    - stages:
 4        - name: 发布操作
 5          script: echo "可用发布任务替代当前任务"
 6        # 发布操作后执行 issue 更新操作
 7        - name: update issue
 8          type: git:issue-update
 9          options:
10            # 关闭 issue
11            state: close
12            # 移除 “预发布” 标签,添加 “已发布” 标签
13            label:
14              add: 已发布
15              remove: 预发布
16            # 当有 “feature” 或 “bug” 标签才进行上述操作
17            when:
18              label:
19                - feature
20                - bug
 1$:
 2  tag_push:
 3    - stages:
 4        - name: changelog
 5          image: cnbcool/changelog
 6          exports:
 7            latestChangeLog: LATEST_CHANGE_LOG
 8        - name: update issue
 9          type: git:issue-update
10          options:
11            fromText: ${LATEST_CHANGE_LOG}
12            label:
13              add: 需求已接收
14            when:
15              label: feature

reviewer

git:reviewer

==配置评审人或处理人==给 PR 添加、删除评审人/处理人,可指定备选评审人/处理人范围。

适用事件

参数

type

操作类型:

reviewers

要 添加 或 删除 的 reviewer 用户名。多个使用 , 或 ; 分隔。

type 为 add-reviewer、remove-reviewer、add-assignee、remove-assignee 时有效。

若同时配置了 reviewers 、 reviewersConfig ,则会在两者中随机选指定数量的评审人或处理人

count

指定要添加的评审人或处理人数量,随机抽取指定数量的评审人或处理人。

如果已有评审人或处理人的数量 < count ,那么补齐。

如果已有评审人或处理人的数量 >= count ,那么什么也不做。

exclude

排除指定的用户。

reviewersConfig

文件评审人或处理人配置,如果配置中有配置当前变更文件的评审人或处理人,则会被添加为评审人或处理人。

type 为 add-reviewer 或 add-assignee 时有效。

支持两种格式:

1reviewersConfig: config.json
1{
2   "./src": "name1,name2",
3   ".cnb.yml": "name3"
4}
1reviewersConfig:
2  ./src: name1,name2
3  .cnb.yml: name3

其中,文件评审人或处理人配置的 key 为文件相对路径;value 为评审人或处理人英文名,用英文逗号分隔。

若同时配置了 reviewers 、reviewersConfig,则会在两者中随机选指定数量的评审人或处理人。

role

评审人或处理人可以添加的角色可选包括:Developer、Master、Owner 如果选择 Developer,则可添加 Developer 及以上权限成员,包括 Developer、Master、Owner

类型定义
REVIEW_OPERATION_TYPE

add-reviewer | add-reviewer-from-repo-members | add-reviewer-from-group-members | add-reviewer-from-outside-collaborator-members | remove-reviewer | add-assignee | remove-assignee

IReviewersConfig
1{
2    [key: String]: String
3}
ROLE_TYPE

Developer | Master | Owner

输出结果

添加评审人的输出结果:

1{
2  // 当前有效的评审人
3  "reviewers": [],
4
5  // reviewers 对应的 at 消息格式,方便发送通知
6  "reviewersForAt": []
7}

添加处理人的输出结果:

1{
2  // 当前有效的处理人
3  "assignees": [],
4
5  // assignees 对应的 at 消息格式,方便发送通知
6  "assigneesForAt": []
7}

配置样例

 1main:
 2  pull_request:
 3    - stages:
 4        - name: 添加评审人
 5          type: git:reviewer
 6          options:
 7            type: add-reviewer
 8            reviewers: aaa;bbb
 9
10        - name: 添加处理人
11          type: git:reviewer
12          options:
13            type: add-assignee
14            reviewers: ccc;ddd
 1main:
 2  pull_request:
 3    - stages:
 4        - name: 删除评审人
 5          type: git:reviewer
 6          options:
 7            type: remove-reviewer
 8            reviewers: aaa
 9
10        - name: 删除处理人
11          type: git:reviewer
12          options:
13            type: remove-assignee
14            reviewers: aaa
 1main:
 2  pull_request:
 3    - stages:
 4        - name: 改配置?需要特别 review
 5          ifModify:
 6            - ".cnb.yml"
 7            - "configs/**"
 8          type: git:reviewer
 9          options:
10            type: add-reviewer
11            reviewers: bbb
12
13        - name: 改配置?需要特别处理
14          ifModify:
15            - ".cnb.yml"
16            - "configs/**"
17          type: git:reviewer
18          options:
19            type: add-assignee
20            reviewers: ccc
 1main:
 2  pull_request:
 3    - stages:
 4        - name: 下班时间发版本?需指定人评审。
 5          if: |
 6            [ $(date +%H) -ge 18 ]
 7          type: git:reviewer
 8          options:
 9            type: add-reviewer
10            reviewers: bbb
11
12        - name: 下班时间发版本?需指定人处理。
13          if: |
14            [ $(date +%H) -ge 18 ]
15          type: git:reviewer
16          options:
17            type: add-assignee
18            reviewers: ccc
 1main:
 2  pull_request:
 3    - stages:
 4        - name: random
 5          image: tencentcom/random
 6          settings:
 7            from:
 8              - aaa
 9              - bbb
10          exports:
11            result: CURR_REVIEWER
12        - name: show  CURR_REVIEWER
13          script: echo ${CURR_REVIEWER}
14        - name: add reviewer
15          type: git:reviewer
16          options:
17            type: add-reviewer
18            reviewers: ${CURR_REVIEWER}
1main:
2  pull_request:
3    - stages:
4        - name: add reviewer
5          type: git:reviewer
6          options:
7            type: add-reviewer-from-repo-members

最佳实践

建立专用的 CR 群,交叉评审自动合并

  1. PR 随机选择N名评审者,通知到群
  2. 评审通过后自动合并
  3. 记录评审者信息在提交信息中
  4. Git 设置满足多人评审自动合并策略实现多人交叉评审
 1main:
 2  review:
 3    - stages:
 4        - name: CR 通过后自动合并
 5          type: git:auto-merge
 6          options:
 7            mergeType: squash
 8            removeSourceBranch: true
 9            mergeCommitMessage: $CNB_LATEST_COMMIT_MESSAGE
10          exports:
11            reviewedBy: REVIEWED_BY
12        # 将评审消息发送到企业微信机器人
13        - name: notify
14          image: tencentcom/wecom-message
15          settings:
16            msgType: markdown
17            robot: "155af237-6041-4125-9340-000000000000"
18            content: |
19              > CR 通过后自动合并 <@${CNB_BUILD_USER}> 
20              >  
21              > ${CNB_PULL_REQUEST_TITLE}
22              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
23              > 
24              > ${REVIEWED_BY}
25
26  pull_request:
27    - stages:
28        # ...省略其它任务
29
30        # 发送到 CR 专用群
31        - name: add reviewer
32          type: git:reviewer
33          options:
34            reviewers: aaa,bbb,ccc,ddd
35            count: 2
36          exports:
37            reviewersForAt: CURR_REVIEWER_FOR_AT
38        - name: notify
39          image: tencentcom/wecom-message
40          settings:
41            msgType: markdown
42            robot: "155af237-6041-4125-9340-000000000000"
43            message: |
44              > ${CURR_REVIEWER_FOR_AT}
45              >  
46              > ${CNB_PULL_REQUEST_TITLE}
47              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
48              >  
49              > from ${CNB_BUILD_USER}

release

git:release

==仓库发布 Release==

适用事件

参数

overlying

叠加模式

::: warning 默认情况下,当 release 版本已经存在时,会先删除这个版本,重新生成。 :::

tag

release 对应的 tag 名,非必填

tag_push 事件无需传入,直接取触发 tag_push 事件的 tag 名。

非 tag_push 事件必填,用来作为 release 对应的 tag 名。

title

release 的标题

description

release 的描述

preRelease

是否将 release 设置为 预发布

latest

是否将 release 设置为最新版本

输出结果

无

配置样例

 1$:
 2  tag_push:
 3    - stages:
 4        - name: changelog
 5          image: cnbcool/changelog
 6          exports:
 7            latestChangeLog: LATEST_CHANGE_LOG
 8        - name: upload release
 9          type: git:release
10          options:
11            title: release
12            description: ${LATEST_CHANGE_LOG}
1main:
2  push:
3    - stages:
4        - name: git release
5          type: git:release
6          options:
7            tag: Nightly
8            description: description

testing

coverage

testing:coverage

==单测覆盖率==,通过单测结果报告,计算单测覆盖率结果,并上报徽章。

适用事件

所有事件

全量覆盖率

coverage coverage coverage coverage

从本地覆盖率报告文件解析而来,目前可识别以下格式的报告:

增量覆盖率

coverage-pr coverage-pr coverage-pr coverage-pr

变更行对应的单测覆盖率,仅支持 pull_request、pull_request.update、pull_request.target 事件

参数

pattern

Glob 格式,指定覆盖率报告文件位置,相对于当前工作目录。 缺省时,将尝试查找当前目录(包括子目录)下的以下文件:coverage.json、jacoco*.xml、lcov.info、*.lcov。

lines

指定全量覆盖率红线,判断如果全量覆盖率百分比小于该值,阻断工作流退出流水线。

diffLines

指定增量覆盖率红线,判断如果全量覆盖率百分比小于该值,阻断工作流退出流水线。 pull_request、pull_request.update、pull_request.target 事件支持计算增量覆盖率结果,其他事件只计算全量覆盖率。

allowExts

参与覆盖率计算的代码文件类型白名单,逗号分隔, 如:.json,.ts,.js。 缺省时报告中的文件都会参与计算。

lang

当覆盖率结果报告目标格式为 golang 时,请指定此参数 为 go,否则会出现计算误差。其他情况可忽略该参数。

breakIfNoCoverage

没有找到覆盖率报告文件时,是否抛出错误终止流程。

输出结果

1{
2  // 代码行覆盖率,例如 100,计算出错时值为 NA
3  "lines": 100,
4  // 代码增量行覆盖率,例如 100,计算出错时值为 NA
5  "diff_pct": 100
6}

配置样例

 1main:
 2  push:
 3    - stages:
 4        - name: coverage
 5          type: testing:coverage
 6          options:
 7            breakIfNoCoverage: false
 8          exports:
 9            lines: LINES
10        - name: result
11          script: echo $LINES

artifact

remove-tag

artifact:remove-tag

==删除 CNB 制品标签==,目前仅删除支持 CNB docker 和 helm 标签。需要有仓库写权限。

适用事件

参数

name

制品包名

tags
type

制品类型,目前仅支持 docker 和 helm

配置样例

 1main:
 2  push:
 3    - stages:
 4        - name: remove tag
 5          type: artifact:remove-tag
 6          options:
 7            # 包名
 8            # 包名示例1,仓库同名制品:reponame
 9            # 包名示例2,仓库非同名制品:reponame/name
10            name: reponame/name
11            tags:
12              - tag1
13              - tag2
14            type: docker