内置任务
在每一阶段（Stage）操作中，除了使用自定义任务， CNB 还扩展了一些常用的内置任务，以供开发者使用。
Docker
cache
docker:cache
==Docker 缓存==，构建一个 Docker 镜像作为缓存，在未来的构建中重复使用。
可以避免网络资源如 依赖包 重复下载。
适用事件
参数
dockerfile
- type:
String - required:
true
用于构建缓存镜像的 Dockerfile 路径。
为避免超长时间构建，Docker 镜像构建超时时间受 job.timeout 参数控制。
by
- type:
Array<String>|String - required:
false
用来声明缓存镜像构建过程中依赖的文件列表。注意：未出现在 by 列表中的文件，除了 Dockerfile，其他在构建镜像过程中，都当不存在处理。
- 支持数组格式
- 支持字符串格式，多个文件用英文逗号分隔。
versionBy
- type:
Array<String>|String - required:
false
用来进行版本控制，未传入 versionBy，则默认取 by 的值进行版本控制。
versionBy 所指向的文件内容发生变化，我们就会认为是一个新的版本， 具体的计算逻辑见这个表达式：sha1(Dockerfile + versionBy + buildArgs + target + arch)。
- 支持数组格式。
- 支持字符串格式，多个文件用英文逗号分隔。
buildArgs
- type:
Object - required:
false
在 build 时插入额外的构建参数 (--build-arg $key=$value), value 值为 null 时只加入 key (--build-arg $key)。
target
- type:
String - required:
false
对应 docker build 中的 –target 参数，可以选择性地构建 Dockerfile 中的特定阶段，而不是构建整个 Dockerfile。
sync
- type:
Boolean - required:
false - default:
false
是否同步模式，等待缓存镜像 docker push 成功后才继续。
ignoreBuildArgsInVersion
- type:
Boolean - required:
false - default:
false
版本计算是否忽略 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
resolve
await-resolve
cnb:awaitcnb:resolve
await 会等待 resolve 的执行，resolve 可以向 await传递变量。
通过 await-resolve，可以让多个并发的 pipeline 相互配合，实现更灵活的顺序控制。
:::tip
await-resolve 同 apply、trigger 的区别：
前者指一个构建中某 pipeline 执行到 await 任务时等待对应 key 的 resolve 通知才会继续进行。
后者指一个 pipeline 触发新事件，开启新的构建。可以跨仓库。可以异步调用，也可以同步等待。
:::
使用限制
- 只能对同一个事件触发的
pipeline进行await和resolve操作 - 一个
key仅能resolve一次，但可以await多次 - 通过
key对await和resolve进行分组
死锁检测
await 和 resolve 相互配合可以完成灵活的流程控制，但也会引入更复杂的边界情况，比如：
pipeline-1和pipeline-2相互await，即：死锁- 多条
pipeline间存在await环，即：间接死锁 await一个不存在的key，或者key没有关联resolve，即：无限等待resolve所在pipeline执行失败，对应的await陷入无限等待- 多个
resolve任务关联同一个key，即重复resolve抛出异常
死锁检测 机制会自动检测以上异常，结束 await 的等待状态，抛出 dead lock found. 异常。
await 和 resolve 的在配置文件中顺序不影响运行结果，即最后 await 任务一定是会等待相应的 resolve 完成，这种情况不会被死锁检测机制终止。
适用事件
await 参数
key
- type: String
- required: true
配对 ID
resolve 参数
key
- type: String
- required: true
配对 ID
data
- type: object
- required: false
要传递的对象
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
适用事件
pushcommit.addbranch.createpull_request.targetpull_request.mergeabletag_pushpull_request.mergedapi_triggerweb_triggercrontabtag_deploy
参数
config
- type:
String - required:
false完整的 CI 配置文件内容
configFrom
- type:
String - required:
false指定一个本地文件作为配置文件。
event
- type:
String - required:
false - default:
api_trigger要执行的自定义事件名，必须为api_trigger或以api_trigger_开头。
sync
- type:
Boolean - required:
false - default:
false是否同步执行。
同步模式下会等待本次 apply 流水线执行成功，再执行下一个任务。
continueOnBuildError
- type:
Boolean - required:
false - default:
false同步模式下，触发的流水线构建失败时，是否继续执行下个任务。
title
- type:
String - required:
false自定义流水线标题
环境变量相关
当前 Job 可见的，业务定义的环境变量全部传递给新的流水线。
默认值中有如下环境变量，用户无法覆盖：
APPLY_TRIGGER_BUILD_ID，含义同 CI 默认环境变量中的CNB_BUILD_IDAPPLY_TRIGGER_PIPELINE_ID，含义同 CI 默认环境变量中的CNB_PIPELINE_IDAPPLY_TRIGGER_REPO_SLUG，含义同 CI 默认环境变量中的CNB_REPO_SLUGAPPLY_TRIGGER_REPO_ID，含义同 CI 默认环境变量中的CNB_REPO_IDAPPLY_TRIGGER_USER，含义同 CI 默认环境变量中的CNB_BUILD_USERAPPLY_TRIGGER_BRANCH，含义同 CI 默认环境变量中的CNB_BRANCHAPPLY_TRIGGER_COMMIT，含义同 CI 默认环境变量中的CNB_COMMITAPPLY_TRIGGER_COMMIT_SHORT，含义同 CI 默认环境变量中的CNB_COMMIT_SHORTAPPLY_TRIGGER_ORIGIN_EVENT，含义同 CI 默认环境变量中的CNB_EVENTCNB_PULL_REQUEST_ID，含义同 CI 默认环境变量中的CNB_PULL_REQUEST_IDCNB_PULL_REQUEST_IID，含义同 CI 默认环境变量中的CNB_PULL_REQUEST_IIDCNB_PULL_REQUEST_MERGE_SHA，含义同 CI 默认环境变量中的CNB_PULL_REQUEST_MERGE_SHA
config 取值优先级
按以下顺序依次取值，取到为止：
configconfigFrom- 当前仓库
.cnb.yml - 若在
pull_request.merged事件中调用apply内置任务，取合并后的配置文件 - 若在
pull_request.target、pull_request.mergeable事件中调用apply内置任务，取目标分支的配置文件 - 其他情况取当前分支配置文件
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
- type: String
- required: true
本地文件路径
输出结果
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
- type:
String - required:
true
个人访问令牌。
新流水线触发者为令牌对应用户，会判断有无目标仓库权限。
slug
- type:
String - required:
true
目标仓库的完整路径，如：group/repo。
event
- type:
String - required:
true
触发的自定义事件名，必须是 api_trigger 或以 api_trigger_ 开头。
需要目标仓库配置了对应事件的流水线，才可以触发。
branch
- type:
String - required:
false
触发分支，默认为主分支。
sha
- type:
String - required:
false
触发分支中的 CommitId，默认取 branch 的最新提交记录。
env
- type: TriggerEnv
- required:
false
触发目标仓库流水线时的环境变量。
默认值中有如下环境变量，用户无法覆盖：
API_TRIGGER_BUILD_ID，含义同 CI 默认环境变量中的CNB_BUILD_IDAPI_TRIGGER_PIPELINE_ID，含义同 CI 默认环境变量中的CNB_PIPELINE_IDAPI_TRIGGER_REPO_SLUG，含义同 CI 默认环境变量中的CNB_REPO_SLUGAPI_TRIGGER_REPO_ID，含义同 CI 默认环境变量中的CNB_REPO_IDAPI_TRIGGER_USER，含义同 CI 默认环境变量中的CNB_BUILD_USERAPI_TRIGGER_BRANCH，含义同 CI 默认环境变量中的CNB_BRANCHAPI_TRIGGER_COMMIT，含义同 CI 默认环境变量中的CNB_COMMITAPI_TRIGGER_COMMIT_SHORT，含义同 CI 默认环境变量中的CNB_COMMIT_SHORT
sync
- type: Boolean
- required: false
- default: false
是否同步执行，同步模式下会等待本次 trigger 流水线执行成功后，再执行下一个任务。
continueOnBuildError
- type: Boolean
- required: false
- default: false
同步模式下，触发的流水线构建失败时，是否继续执行下个任务。
title
- type: String
- required: false
自定义流水线标题
类型定义
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
远程开发中是否配置该内置任务的区别：
- ==使用该任务==： 启动云原生开发时，需等待该任务执行完，才出现 WebIDE 和 VSCode/Cursor 客户端入口。
- ==不使用该任务==： 流水线 prepare 阶段执行完（code-server 代码服务启动），stages 任务执行前，就会出现 WebIDE 和 VSCode/Cursor 客户端入口。
上述入口出现时机区别：仅指从 loading 等待页到跳转入口选择页出现的时机。 实际上无论是否使用该任务，在 code-server 代码服务启动后，远程开发已经是可用状态。
注意：使用该任务将增加等待时间。如果需要延迟开发者进入时机，在某些任务执行完才允许进入远程开发环境，可使用该任务。
适用事件
vscodebranch.createapi_triggerweb_trigger
输出结果
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
type:
Stringrequired: false
default: auto
合并策略，默认为 auto：如果多人提交走 merge ，否则走 squash 。
mergeCommitMessage
- type: String
- required: false
- 合并点提交信息。
当合并策略为 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
- type:
String - required:
false
合并点需要设置的脚注，多个脚注用 \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
- type: Boolean
- required: false
- default: false
合并后是否删除源分支。
源分支与目标分支不同仓库时，该值无效。
ignoreAssignee
- type: Boolean
- required: false
- default: false
是否忽略 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 事件流程负责的问题，这里的设定是这样的：
- 如果提出
PR者，是目标仓库的成员，那么提出PR的人对后续产生的push事件流程负责（即push构建流水会推送到这里）。 - 如果提出
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 群交叉走查自动合并
- 走查通过后自动合并
- 记录走查者信息在提交信息中
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 获取方式
- 如果传入了
fromText参数，则从fromText中获取。其中branch.delete必传fromText（分支已删除，无法从上下文中获取）。 - 如果没传入
fromText参数，则从上下文中获取。push事件：从本次推送的所有commit的提交日志中获取。- 合并请求类事件：从合并请求中的所有
commit的提交日志中获取。 - 其他事件：从最新的一个
commit的提交日志中获取。
获取方式：提取上述文本中如下两种格式
- #issueID：表示当前仓库的 issue。例如 #123，表示当前仓库 id 为 123 的 issue。
- groupName/repoName#issueID：表示跨仓库（其他仓库）的 issue。例如：test/test#123，表示 test/test 仓库中 id 为 123 的 issue。
注意 #123 或 test/test#123 前需要有空格。
提交日志中如何带上 Issue ID
提交代码时，可以在提交日志中加上关联的 Issue ID， 可以在使用当前内置任务时可以自动提取到关联 Issue，用来更新 Issue 标签和状态
推荐在提交日志的 body 中带上 Issue ID，命令行操作方式如下：
- 方法一：用
shift + enter换行，建议 title 和 body 之间加上一个空行
1git commit -m "fix(云原生构建): 修复一个错误
2
3cnb/feedback#123"
- 方法二：
以下提交方式 title 和 body 之间会产生两个换行
1git commit -m "fix(云原生构建): 修复一个错误" -m "cnb/feedback#123"
参数
fromText
- type:
String - required:
false
从给定的文本中解析 Issue Id。
不声明时，自动从上下文里的提交记录解析。
可以指定一个包含 issue id 引用的文本来声明操作对象，比如： ${LATEST_CHANGE_LOG} 。
state
- type: IssueStateMap
- required:
false
对应 state 属性，为 close 时，可关闭 Issue。
label
- type: IssueUpdateLabel
- required:
false
对 label 的操作描述。
when
- type: IssueUpdateStatus
- required:
false
过滤条件，多个条件之间是 or 关系。为空时表示对所有 Issue 操作。
lint
- type: IssueUpdateStatus
- required:
false
检查 Issue 是否满足条件，不满足时抛出异常，多个条件之间是 or 关系，为空时表示不做检查。
defaultColor
- type:
String - required:
false
添加的标签的默认颜色，当有传入 label.add 参数时才有效。
类型定义
IssueStateMap
Enum<String>
open | close
IssueUpdateLabel
add
- type:
Array<String>|String - required:
false - 要添加的标签列表，标签不存在时，会自动创建。
- type:
remove
- type:
Array<String>|String - required:
false - 要移除的标签列表
- type:
IssueUpdateStatus
- label
- type:
Array<String>|String - required:
false - 标签，多个值之间是
or关系
- type:
输出结果
1{
2 issues // issue 列表
3}
配置样例
- 合并到 main 后，更新标签
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
- tag_push 时，关闭 issue，更新标签
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
- 根据 changelog 添加标签
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 添加、删除评审人/处理人，可指定备选评审人/处理人范围。
适用事件
pull_requestpull_request.targetpull_request.update
参数
type
- type: REVIEW_OPERATION_TYPE
- required:
false - default:
add-reviewer
操作类型：
add-reviewer: 添加评审人，会从reviewers参数中选择指定数量的评审人add-reviewer-from-repo-members: 从仓库直接成员里选一名，添加为评审人add-reviewer-from-group-members: 从仓库父组织（直接上级组织）里选一名，添加为评审人add-reviewer-from-outside-collaborator-members: 从仓库的外部协作者里选一名，添加为评审人remove-reviewer: 从已有的评审人中删除指定的成员add-assignee: 添加处理人，添加reviewers参数传入的成员remove-assignee: 从已有的处理人中删除指定的成员
reviewers
- type:
Array<String>|String - required:
false
要 添加 或 删除 的 reviewer 用户名。多个使用 , 或 ; 分隔。
type 为 add-reviewer、remove-reviewer、add-assignee、remove-assignee 时有效。
若同时配置了 reviewers 、 reviewersConfig ，则会在两者中随机选指定数量的评审人或处理人
count
- type:
Number - required:
false
指定要添加的评审人或处理人数量，随机抽取指定数量的评审人或处理人。
- 当
type=add-reviewer，count 缺省值为reviewers的数量，即全部添加 - 当
type=add-reviewer-from-repo-members，count 缺省值为 1 - 当
type=add-reviewer-from-group-members，count 缺省值为 1 - 当
type=add-reviewer-from-outside-collaborator-members，count 缺省值为 1 - 当
type=add-assignee，count 缺省值为reviewers的数量，即全部添加
如果已有评审人或处理人的数量 < count ，那么补齐。
如果已有评审人或处理人的数量 >= count ，那么什么也不做。
exclude
- type:
Array<String>|String - required:
false
排除指定的用户。
reviewersConfig
- type: IReviewersConfig |
String - required:
false
文件评审人或处理人配置，如果配置中有配置当前变更文件的评审人或处理人，则会被添加为评审人或处理人。
type 为 add-reviewer 或 add-assignee 时有效。
支持两种格式：
- 字符串格式，传入配置文件相对路径(支持
json文件)：
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
- type: ROLE_TYPE
- required:
false
评审人或处理人可以添加的角色可选包括：Developer、Master、Owner 如果选择 Developer，则可添加 Developer 及以上权限成员，包括 Developer、Master、Owner
类型定义
REVIEW_OPERATION_TYPE
Enum<String>
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
Enum<String>
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
- 结合 ifModify，指定文件被修改时添加评审人和处理人
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
- 结合 if，在指定条件下将某些人添加为评审人或处理人
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}
- 从当前仓库成员里选一名评审人进行 review
1main:
2 pull_request:
3 - stages:
4 - name: add reviewer
5 type: git:reviewer
6 options:
7 type: add-reviewer-from-repo-members
最佳实践
建立专用的 CR 群，交叉评审自动合并
PR随机选择N名评审者，通知到群- 评审通过后自动合并
- 记录评审者信息在提交信息中
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==
适用事件
pushcommit.addbranch.createtag_pushpull_request.mergedapi_triggerweb_triggertag_deploy
参数
overlying
- type:
Boolean - required:
false - default:
false
叠加模式
true：叠加模式，同一个release可以提交多次，最终的release是多次提交的并集。如果同名附件已经存在，会先删除再上传，达到更新的效果。false：非叠加模式，以最后一个提交的为准，前面的会被清除。
::: warning 默认情况下，当 release 版本已经存在时，会先删除这个版本，重新生成。 :::
tag
- type:
String - required:
false
release 对应的 tag 名，非必填
tag_push 事件无需传入，直接取触发 tag_push 事件的 tag 名。
非 tag_push 事件必填，用来作为 release 对应的 tag 名。
title
- type:
String - required:
false - default:
tag名
release 的标题
description
- type:
String - required:
false
release 的描述
preRelease
- type:
Boolean - required:
false - default:
false
是否将 release 设置为 预发布
latest
- type: “true” | “false” | true | false
- required:
false - default:
false
是否将 release 设置为最新版本
输出结果
无
配置样例
- 生成 changelog 并自动更新 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}
- 主分支 push 时发布 release
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
==单测覆盖率==，通过单测结果报告，计算单测覆盖率结果，并上报徽章。
适用事件
全量覆盖率
从本地覆盖率报告文件解析而来，目前可识别以下格式的报告：
json(js)（推荐使用）json-summarylcov（推荐使用）jacocogolang
增量覆盖率
变更行对应的单测覆盖率，仅支持 pull_request、pull_request.update、pull_request.target 事件
参数
pattern
- type:
String - required:
false
Glob 格式，指定覆盖率报告文件位置，相对于当前工作目录。 缺省时，将尝试查找当前目录（包括子目录）下的以下文件：coverage.json、jacoco*.xml、lcov.info、*.lcov。
lines
- type:
Number - required:
false
指定全量覆盖率红线，判断如果全量覆盖率百分比小于该值，阻断工作流退出流水线。
diffLines
- type:
Number - required:
false
指定增量覆盖率红线，判断如果全量覆盖率百分比小于该值，阻断工作流退出流水线。 pull_request、pull_request.update、pull_request.target 事件支持计算增量覆盖率结果，其他事件只计算全量覆盖率。
allowExts
- type:
String - required:
false
参与覆盖率计算的代码文件类型白名单，逗号分隔, 如：.json,.ts,.js。 缺省时报告中的文件都会参与计算。
lang
- type:
String - required:
false
当覆盖率结果报告目标格式为 golang 时，请指定此参数 为 go，否则会出现计算误差。其他情况可忽略该参数。
breakIfNoCoverage
- type:
Boolean - required:
false
没有找到覆盖率报告文件时，是否抛出错误终止流程。
输出结果
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 标签。需要有仓库写权限。
适用事件
pushcommit.addtag_pushtag_deploypull_request.mergedapi_triggerweb_triggercrontabbranch.create
参数
name
- type:
String - required:
true
制品包名
tags
- type:
Array<string> - required: true
type
- type:
String - required:
false - default:
docker
制品类型，目前仅支持 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