内置任务

14692 字约 49 分钟

每个阶段（Stage）中除了自定义任务外，CNB 还提供了一系列常用内置任务，方便开发者直接使用。

总览

docker:
- cache: 构建 Docker 镜像缓存，加速依赖安装
cnb:
- await-resolve: 等待/通知机制，多流水线协作
- apply: 触发同仓库下的子流水线
- trigger: 触发指定仓库下的子流水线
- read-file: 导出文件内容为环境变量
- destroy-token: 销毁流水线 CNB_TOKEN
vscode:
- go: 控制云原生开发环境可用时机
git:
- reviewer: PR 自动添加评审人
- auto-merge: PR 自动合并
- issue-update: 更新 Issue 状态
- release: 仓库发布 Release
- pr-commit-message-preset: 预先设置 PR 的提交信息
- pr-update: 更新 PR 的标题、标签
testing:
- coverage: 单测覆盖率上报
artifact
- remove-tag: 删除 CNB 制品标签
tapd
- status-update: 更新 TAPD 关联项（story、task 或 bug）状态
- comment: 提交 TAPD 关联项（story、task 或 bug）评论
knowledge:
- update: 构建仓库的文档、Issue 等，并将其写入知识库中
npc:
- go: 执行 NPC 任务

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

是否同步模式，true 时会等待缓存镜像 push 成功后再继续后续任务。

ignoreBuildArgsInVersion

type: Boolean
required: false
default: false

版本计算是否忽略 buildArgs。

参见版本控制

输出结果

{
  // 缓存对应的 docker image name
  name;
}

配置样例

.cnb.yml
main:
  push:
    - docker:
        image: node:14
      stages:
        - name: build cache image
          type: docker:cache
          options:
            dockerfile: cache.dockerfile
            # by 支持以下两种形式：数组、字符串
            by:
              - package.json
              - package-lock.json
            # versionBy: package-lock.json
            versionBy:
              - package-lock.json
          exports:
            name: DOCKER_CACHE_IMAGE_NAME
        - name: use cache
          image: $DOCKER_CACHE_IMAGE_NAME
          # 将 cache 中的文件拷贝过来使用
          commands:
            - cp -r "$NODE_PATH" ./node_modules
        - name: build with cache
          script:
            - npm run build

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

# 选择一个 Base 镜像
FROM node:14

# 设置工作目录
WORKDIR /space

# 将 by 中的文件列表 COPY 过来
COPY . .

# 根据 COPY 过来的文件进行依赖的安装
RUN npm ci

# 设置好需要的环境变量
ENV NODE_PATH=/space/node_modules

cnb

await-resolve

cnb:await
cnb:resolve

await 会等待 resolve 执行完成，resolve 可以向 await 传递变量。

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

提示

await-resolve 同 apply、trigger 的区别：

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

后者指一个 pipeline 触发新的 pipeline，支持异步调用、同步等待和跨仓库触发。

使用限制

只能对 同一个事件 触发的 pipeline 进行 await 和 resolve 操作
一个 key 仅能 resolve 一次，但可以 await 多次
通过 key 对 await 和 resolve 进行分组
await-resolve 任务只能运行在流水线的 stages 中，不能运行在 endStages 和 failStages 中

死锁检测

await 和 resolve 相互配合可以实现灵活的流程控制，但也可能引入更复杂的边界情况，例如：

死锁
- pipeline-1 和 pipeline-2 相互 await
- 多条 pipeline 间存在 await 环
无限等待
- await 一个不存在的 key，或者 key 没有关联 resolve
- resolve 所在 pipeline 执行失败
重复 resolve
- 多个 resolve 任务关联同一个 key

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

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

await 参数

resolve 参数

data

type: object
required: false

要传递的对象

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

- name: resolve a json
  type: cnb:resolve
  options:
    key: demo
    data:
      a: 1
      b:
        c: 2

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

- name: await a json
  type: cnb:await
  options:
    key: demo
  exports:
    a: VAR_A
    b.c: VAR_B
- name: show var
  script:
    - echo ${VAR_A} # 1
    - echo ${VAR_B} # 2

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

- name: ready
  type: cnb:resolve
  options:
    key: i-am-ready

- name: ready
  type: cnb:await
  options:
    key: i-am-ready

输出结果

{
  // resolve 返回的 data 内容
  data;
}

apply

cnb:apply

在当前仓库中，触发当前仓库的自定义事件流水线。

适用事件

push
commit.add
branch.create
pull_request.target
pull_request.mergeable
tag_push
pull_request.merged
api_trigger
web_trigger
crontab
tag_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

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

环境变量相关

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

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

APPLY_TRIGGER_BUILD_ID，含义同 CI 默认环境变量中的 CNB_BUILD_ID
APPLY_TRIGGER_PIPELINE_ID，含义同 CI 默认环境变量中的 CNB_PIPELINE_ID
APPLY_TRIGGER_REPO_SLUG，含义同 CI 默认环境变量中的 CNB_REPO_SLUG
APPLY_TRIGGER_REPO_ID，含义同 CI 默认环境变量中的 CNB_REPO_ID
APPLY_TRIGGER_USER，含义同 CI 默认环境变量中的 CNB_BUILD_USER
APPLY_TRIGGER_BRANCH，含义同 CI 默认环境变量中的 CNB_BRANCH
APPLY_TRIGGER_COMMIT，含义同 CI 默认环境变量中的 CNB_COMMIT
APPLY_TRIGGER_COMMIT_SHORT，含义同 CI 默认环境变量中的 CNB_COMMIT_SHORT
APPLY_TRIGGER_ORIGIN_EVENT，含义同 CI 默认环境变量中的 CNB_EVENT
CNB_PULL_REQUEST_ID，含义同 CI 默认环境变量中的 CNB_PULL_REQUEST_ID
CNB_PULL_REQUEST_IID，含义同 CI 默认环境变量中的 CNB_PULL_REQUEST_IID
CNB_PULL_REQUEST_MERGE_SHA，含义同 CI 默认环境变量中的 CNB_PULL_REQUEST_MERGE_SHA

Config 取值优先级

按以下顺序依次取值，取到为止：

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

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

输出结果

{
  "sn": "cnb-i5o-1ht8e12hi", // 构建号
  "buildLogUrl": "https://cnb.cool/<your-repo-slug>/-/build/logs/cnb-i5o-1ht8e12hi", // 构建日志链接
  "message": "success",
  "buildSuccess": true, // 触发的构建是否成功，此key仅在同步模式下存在
  "lastJobExports": {} // 触发的流水线最后一个job导出的环境变量
}

配置样例

以下示例展示了 cnb:apply 的几种常用方式：

使用 configFrom 引用本地配置文件：

.cnb.yml
main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            configFrom: ./test/.cnb.yml
            event: api_trigger_test

使用 config 内联配置：

.cnb.yml
main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            config: |
              main:
                api_trigger_test: 
                - stages:
                  - name: test
                    script: echo test
            event: api_trigger_test

触发当前配置文件中定义的其他事件：

.cnb.yml
main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            event: api_trigger_test
  api_trigger_test:
    - stages:
        - name: test
          script: echo test

同步模式（等待子流水线执行完成）：

.cnb.yml
main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            configFrom: .xxx.yml
            event: api_trigger_test
            sync: true

trigger

cnb:trigger

在当前仓库中，触发指定仓库的自定义事件流水线（需要有触发对应仓库流水线的权限）。

参数

token

type: String
default: 环境变量 CNB_TOKEN

个人访问令牌。

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

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_ID
API_TRIGGER_PIPELINE_ID，含义同 CI 默认环境变量中的 CNB_PIPELINE_ID
API_TRIGGER_REPO_SLUG，含义同 CI 默认环境变量中的 CNB_REPO_SLUG
API_TRIGGER_REPO_ID，含义同 CI 默认环境变量中的 CNB_REPO_ID
API_TRIGGER_USER，含义同 CI 默认环境变量中的 CNB_BUILD_USER
API_TRIGGER_BRANCH，含义同 CI 默认环境变量中的 CNB_BRANCH
API_TRIGGER_COMMIT，含义同 CI 默认环境变量中的 CNB_COMMIT
API_TRIGGER_COMMIT_SHORT，含义同 CI 默认环境变量中的 CNB_COMMIT_SHORT

sync

type: Boolean
required: false
default: false

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

continueOnBuildError

type: Boolean
required: false
default: false

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

类型定义

TriggerEnv

{
    [key: String]: String | Number | Boolean
}

输出结果

{
  "sn": "cnb-i5o-1ht8e12hi", // 构建号
  "buildLogUrl": "https://cnb.cool/<your-repo-slug>/-/build/logs/cnb-i5o-1ht8e12hi", // 构建日志链接
  "message": "success",
  "buildSuccess": true, // 触发的构建是否成功，此key仅在同步模式下存在
  "lastJobExports": {} // 触发的流水线最后一个job导出的环境变量
}

配置样例

基本使用

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

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

使用访问令牌 $TOKEN 查询用户是否有触发目标仓库流水线权限。

cnb.yml
main:
  push:
    - stages:
        - name: trigger
          type: cnb:trigger
          imports: https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/envs.yml
          options:
            token: $TOKEN
            slug: a/b
            branch: main
            event: api_trigger_test

read-file

cnb:read-file

读取指定文件内容，可导出为环境变量供后续任务使用。

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

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

imports 仅支持远端仓库中已存在的文件，该内置任务仅支持读取本地文件。

文件类型通过后缀判断，目前支持 .json、.yml、.yaml 和纯文本（key=value 结构）。

输出结果

{
  // 读到的对象
}

配置样例

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

myJson.json
{
  "myVar": "myVar",
  "deep": {
    "myVar": "myVar in deep"
  },
  "deepWithEnvKey": {
    "myVar": "myVar in deepWithEnvKey"
  }
}

cnb.yml
main:
  push:
    - env:
        myKey: deepWithEnvKey
      stages:
        - name: write env file
          script: echo "write env to myJson.json"
        - name: export env
          type: cnb:read-file
          options:
            filePath: myJson.json
          exports:
            myVar: ENV_MY_VAR
            deep.myVar: ENV_DEEP_MY_VAR # 指定多级的key
            $myKey.myVar: ENV_ENV_KEY_MY_VAR # 通过环境变量指定获取的key
        - name: echo env
          script:
            - echo $ENV_MY_VAR
            - echo $ENV_DEEP_MY_VAR
            - echo $ENV_ENV_KEY_MY_VAR

destroy-token

cnb:destroy-token

流水线启动前会创建 CNB_TOKEN，结束后会自动销毁。使用该任务可提前销毁 CNB_TOKEN 并移除对应环境变量。

配置样例

流水线中使用 CNB_TOKEN 后主动销毁，降低令牌滥用风险。

cnb.yml
main:
  push:
    - stages:
        - name: use CNB_TOKEN
          script: echo "Make API calls using the CNB_TOKEN."
        - name: destroy token
          type: cnb:destroy-token

vscode

go

vscode:go

云原生开发中是否配置该内置任务的区别：

使用该任务：启动云原生开发时，需等待该任务执行完成，才会出现 WebIDE 和 VSCode/Cursor 客户端入口。
不使用该任务：流水线 prepare 阶段执行完成（code-server 代码服务启动）， stages 任务执行前，就会出现 WebIDE 和 VSCode/Cursor 客户端入口。

上述入口出现时机差异：仅指从 loading 等待页到跳转入口选择页出现的时机。实际上无论是否使用该任务，在 code-server 代码服务启动后，云原生开发已处于可用状态。

注意：使用该任务会增加等待时间。如果需要在某些任务执行完才允许进入云原生开发环境，可使用该任务。

适用事件

vscode
branch.create
api_trigger
web_trigger

输出结果

{
  // webide url
  "url": ""
}

配置样例

.cnb.yml
$:
  # vscode 事件：专供页面中启动云原生开发用
  vscode:
    - docker:
        # 使用自定义镜像作为开发环境，未传入此参数，
        # 将使用默认镜像 cnbcool/default-dev-env:latest
        image: cnbcool/default-dev-env:latest
      services:
        - vscode
        - docker
      stages:
        # 希望等该任务执行完再进入开发环境
        - name: ls
          script: ls -al
        - name: vscode go
          type: vscode:go
        # 可以在进入开发环境后再执行的任务
        - name: ls
          script: ls -al

git

auto-merge

git:auto-merge

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

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

参数

mergeType

type: merge | squash | rebase | auto
required: false
default: auto

合并策略，默认为 auto：多人提交时走 merge，否则走 squash。

mergeCommitMessage

type: String
required: false

合并点提交信息。

当合并策略为 rebase 的时候，该信息无效，无需填写。
当合并策略为 merge 时，默认为 chore: merge node(merged by CNB) ，会自动追加 PR 引用、评审人名单、PR 包含的提交人名单。举例说明：

chore: merge node(merged by CNB)

PR-URL: !916
Reviewed-By: tom
Reviewed-By: jerry
Co-authored-by: jack

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

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: squash

该配置会产生如下效果：

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

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

feat(model-a): 给模块 A 增加一个新特性

由于某某原因，新增某某特性

close #10

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

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

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

feat(model-a): 给模块 A 增加一个新特性

由于某某原因，新增某某特性

close #10

PR-URL: !3976
Reviewed-By: tom
Reviewed-By: jerry
Co-authored-by: jack

也可以直接指定

如通过环境变量指定为当前 PR 的标题：

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeCommitMessage: $CNB_PULL_REQUEST_TITLE

mergeCommitFooter

type: String
required: false

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

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

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

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: squash
            mergeCommitMessage: "add feature for some jobs"
            mergeCommitFooter: "--story=123\n--story=456"

add feature for some jobs

--story=123
--story=456
PR-URL: #916
Reviewed-By: tom
Reviewed-By: jerry
Co-authored-by: jack

removeSourceBranch

type: Boolean
required: false
default: false

合并后是否删除源分支。

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

ignoreAssignee

type: Boolean
required: false
default: false

是否忽略 assignee。

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

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

allowAssigneeApprovedMerge

type: Boolean
required: false
default: false

当 PR 的处理人已经批准时，是否允许自动合并。

当该值为 true，且当前 PR 的 reviewers 中存在 state 为 approved 的处理人时，自动合并会按 ignoreAssignee 为 true 的逻辑执行。

如果 PR 有多个处理人，只要其中任意一个处理人已批准，即允许自动合并。

输出结果

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

配置样例

单独使用

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: merge

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

配合目标分支的 `push` 事件使用

.cnb.yml
main:
  push:
    - stages:
        - name: build
          script: npm run build
        - name: publish
          script: npm run publish
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: merge

当分支 main 上的 PR 触发了 pull_request.mergeable 事件，那么会将这个 PR 以 merge 的方式自动合并。在合并之后，最后一个评审通过的评审者会作为触发者，触发目标分支（main）上的 push 事件，继续执行声明的 build 和 publish 流程。

最佳实践

使用 `squash` 自动合并

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

.cnb.yml
main:
  review:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: squash
            removeSourceBranch: true

使用 `auto` 自动选择合并类型

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

.cnb.yml
main:
  review:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: auto

建立专用的 CR 群交叉走查自动合并

走查通过后自动合并
记录走查者信息在提交信息中

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: CR 通过后自动合并
          type: git:auto-merge
          options:
            mergeType: squash
            mergeCommitMessage: $CNB_LATEST_COMMIT_MESSAGE
          exports:
            reviewedBy: REVIEWED_BY
        - name: notify
          image: tencentcom/wecom-message
          settings:
            robot: "155af237-6041-4125-9340-000000000000"
            msgType: markdown
            content: |
              > CR 通过后自动合并 <@${CNB_BUILD_USER}> 
              > 　
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              > 
              > ${REVIEWED_BY}

  pull_request:
    - stages:
        # ...省略其他任务
        - name: notify
          image: tencentcom/wecom-message
          options:
            robot: "155af237-6041-4125-9340-000000000000"
            msgType: markdown
            content: |
              > ${CURR_REVIEWER_FOR_AT}
              > 
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              > 
              > from ${CNB_BUILD_USER}

issue-update

git:issue-update

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

工作机制

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

Issue 获取方式

1. 当传入 fromFile 或 fromText 参数时：

从传入的文本文件或文本中解析获取。fromFile 优先级高于 fromText。

2. 当未传入 fromFile 或 fromText 参数时：

Issue 相关事件：
取当前 Issue。
PR 相关事件：
从该 PR 的 commits 的提交日志中解析获取。
commit.add 事件：
从新增 commits 的提交日志中解析获取。
非新建分支的 push 事件：
从本次推送 commits 的提交日志中解析获取。
其他情况：
从最新 commit 的提交日志中解析获取。

提示

如果需要在 branch.delete 事件中使用，由于分支已删除，无法从上下文中获取，需要使用 fromText 或者 fromFile 参数提供解析内容。

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

#IssueID：表示当前仓库的 Issue。例如 #123，表示当前仓库 id 为 123 的 Issue。
groupName/repoName#IssueID：表示跨仓库（其他仓库）的 Issue。例如：test/test#123，表示 test/test 仓库中 id 为 123 的 Issue。

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

提交日志中如何带上 `IssueID`

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

推荐在提交日志的 body 中带上 IssueID，命令行操作方式如下：

方法一：用 shift + enter 换行，建议 title 和 body 之间加上一个空行

git commit -m "fix(云原生构建): 修复一个错误

cnb/feedback#123"

方法二：

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

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

参数

fromText

type: String
required: false

从给定的文本中解析 IssueId。

不声明时，自动从上下文里的提交记录解析。可以指定一个包含 IssueId 引用的文本来声明操作对象，比如配合变更日志生成插件一起使用，将变更日志中的 IssueId 自动提取出来。

fromFile

type: String
required: false

从文本文件中读取内容并解析 IssueId。优先级高于 fromText。

当内容过多时，建议使用该参数，将内容通过文件传递，避免超出限制。

state

type: IssueStateMap
required: false

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

label

type: UpdateLabel
required: false

对 label 的操作描述。

assignee

type: UpdateAssignee
required: false

对 处理人 的操作描述。

when

type: IssueUpdateStatus
required: false

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

lint

type: IssueUpdateStatus
required: false

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

defaultColor

type: String
required: false

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

prefix

type: String[]
required: false

需要处理的 issue 前缀，例如如果传入的是 close 和 closed，则会处理所有带有 close 和 closed 前缀的 issue。例如 close #123 或 closed #123 #456

类型定义

UpdateLabel

add
- type: Array<String> | String
- required: false

要添加的标签列表，标签不存在时，会自动创建。

remove
- type: Array<String> | String
- required: false

要移除的标签列表

UpdateAssignee

add
- type: Array<String> | String
- required: false

要添加的处理人列表。

remove
- type: Array<String> | String
- required: false

要移除的处理人列表

IssueUpdateStatus

label
- type: Array<String> | String
- required: false

标签，多个值之间是 or 关系

输出结果

{
    issues // issue 列表
}

权限检查

若需要更新的 Issue 属于流水线所属仓库，且非 pull_request, pull_request.update, pull_request.approved, pull_request.changes_requested 事件，则不会检查流水线触发者是否拥有修改 Issue 的权限。

配置样例

合并到 main 后，更新标签

.cnb.yml
main:
  push:
    - stages:
        - name: update issue
          type: git:issue-update
          options:
            # 移除 “开发中” 标签，添加 “预发布” 标签
            label:
              add: 预发布
              remove: 开发中
            # 当有 “feature” 或 “bug” 标签才进行上述标签操作
            when:
              label:
                - feature
                - bug

Tag push 时，关闭 Issue，更新标签

.cnb.yml
$:
  tag_push:
    - stages:
        - name: 发布操作
          script: echo "可用发布任务替代当前任务"
        # 发布操作后执行 issue 更新操作
        - name: update issue
          type: git:issue-update
          options:
            # 关闭 issue
            state: close
            # 可选择指定需要关闭的 issue 前缀，
            # 如果设置了，则包含 close #123 或
            # closed #123 这种才会被关闭
            # prefix:
            #   - close
            #   - closed
            # 移除 “预发布” 标签，添加 “已发布” 标签
            label:
              add: 已发布
              remove: 预发布
            # 当有 “feature” 或 “bug” 标签才进行上述操作
            when:
              label:
                - feature
                - bug

Tag push 时，根据当前 tag 和前一个 tag 的变更内容，找到变更内容中包含的 IssueId，并添加标签

.cnb.yml
$:
  tag_push:
    - stages:
        - name: changelog
          image: cnbcool/changelog
          settings:
            latestChangeLogTarget: LATEST_CHANGELOG.md
        - name: update issue
          type: git:issue-update
          options:
            fromFile: LATEST_CHANGELOG.md
            label:
              add: 需求已接收
            when:
              label: feature

reviewer

git:reviewer

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

适用事件

pull_request
pull_request.target
pull_request.update

pull_request 和 pull_request.update 事件下会检查触发者是否有权限操作评审人/处理人。 pull_request.target 事件下则不会。对于跨仓提交的 PR，可能存在触发者无权限的情况。此时推荐使用 pull_request.target 事件。

参数

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

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

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

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

count

type: Number
required: false

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

当 type 为 add-reviewer 或 add-assignee 时，count 缺省值为 reviewers 的数量，即全部添加
当 type 为 add-reviewer-from-repo-members、add-reviewer-from-group-members 或 add-reviewer-from-outside-collaborator-members 时：
- 若目标分支为保护分支且设置了需要评审人批准，count 缺省值为需要批准的评审人数量
- 其他情况，count 缺省值为 1

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

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

exclude

type: Array<String> | String
required: false

排除指定的用户。

reviewersConfig

type: IReviewersConfig | String
required: false

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

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

支持两种格式：

字符串格式，传入配置文件相对路径。当文件名（大小写不敏感）为 codeowners 时，按 CODEOWNERS 格式解析；否则按 JSON 格式解析。

CODEOWNERS 格式（推荐路径：.cnb/codeowners）：

{
  "reviewersConfig": ".cnb/codeowners"
}

文件内容示例（每行 pattern @owner1 @owner2）：

.cnb/codeowners
# 通用规则写前，具体规则写后
*                       @global-team
*.js                    @fe-team
/src/frontend/          @frontend-owner
/src/frontend/auth.js   @security-team

CODEOWNERS 语法规则：

每行格式为 <pattern> @owner1 @owner2 ...，pattern 遵循 gitignore 风格匹配。
最后匹配的 pattern 优先级最高（通用规则写前，具体规则写后）。
# 开头的行为注释。
无 owner 的 pattern 表示排除该路径。
当前仅支持 @username 形式的 owner 解析为仓库成员；邮箱格式与 @org/team 会被忽略并打印告警。

注意

文件从任务执行时的 workspace 读取，对应当前 ref（PR 事件时为来源分支），与仓库级 CODEOWNERS 必须批准（从目标分支读取）是独立机制。

JSON 格式：

{
  "reviewersConfig": "config.json"
}

config.json
{
  "./src": "name1,name2",
  ".cnb.yml": "name3"
}

对象格式，传入文件评审人配置（仅 JSON 格式，不支持 CODEOWNERS）：

{
  "reviewersConfig": {
    "./src": "name1,name2",
    ".cnb.yml": "name3"
  }
}

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

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

role

type: ROLE_TYPE
required: false

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

skip_on_wip

type: Boolean
required: false
default: true

是否跳过 WIP 状态的 PR（PR 标题开头带有 [WIP] 标记），默认跳过 WIP 状态的 PR。

true: 当 PR 为 WIP 状态时，不会添加评审人或处理人。
false: 当 PR 为 WIP 状态时，仍会添加评审人或处理人。

类型定义

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

{
    [key: String]: String
}

ROLE_TYPE

Enum<String>: Developer | Master | Owner

输出结果

添加评审人的输出结果：

{
  // 当前有效的评审人
  "reviewers": [],

  // reviewers 对应的 at 消息格式，方便发送通知
  "reviewersForAt": []
}

添加处理人的输出结果：

{
  // 当前有效的处理人
  "assignees": [],

  // assignees 对应的 at 消息格式，方便发送通知
  "assigneesForAt": []
}

配置样例

添加评审人和处理人

.cnb.yml
main:
  pull_request:
    - stages:
        - name: 添加评审人
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: aaa;bbb

        - name: 添加处理人
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc;ddd

删除指定成员的评审人和处理人

.cnb.yml
main:
  pull_request:
    - stages:
        - name: 删除评审人
          type: git:reviewer
          options:
            type: remove-reviewer
            reviewers: aaa

        - name: 删除处理人
          type: git:reviewer
          options:
            type: remove-assignee
            reviewers: aaa

结合 ifModify，指定文件被修改时添加评审人和处理人

.cnb.yml
main:
  pull_request:
    - stages:
        - name: 改配置？需要特别 review
          ifModify:
            - ".cnb.yml"
            - "configs/**"
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: bbb

        - name: 改配置？需要特别处理
          ifModify:
            - ".cnb.yml"
            - "configs/**"
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc

结合 if，在指定条件下将某些人添加为评审人或处理人

.cnb.yml
main:
  pull_request:
    - stages:
        - name: 下班时间发版本？需指定人评审。
          if: |
            [ $(date +%H) -ge 18 ]
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: bbb

        - name: 下班时间发版本？需指定人处理。
          if: |
            [ $(date +%H) -ge 18 ]
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc

随机选择一名负责人走查代码

.cnb.yml
main:
  pull_request:
    - stages:
        - name: random
          image: tencentcom/random
          settings:
            from:
              - aaa
              - bbb
          exports:
            result: CURR_REVIEWER
        - name: show  CURR_REVIEWER
          script: echo ${CURR_REVIEWER}
        - name: add reviewer
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: ${CURR_REVIEWER}

从当前仓库成员里选一名评审人进行评审

.cnb.yml
main:
  pull_request:
    - stages:
        - name: add reviewer
          type: git:reviewer
          options:
            type: add-reviewer-from-repo-members

最佳实践

自动随机分配评审人并通知

PR 随机选择 N 名评审者，发送通知到企业微信：

.cnb.yml
main:
  pull_request:
    - stages:
        - name: add reviewer
          type: git:reviewer
          options:
            reviewers: aaa,bbb,ccc,ddd
            count: 2
          exports:
            reviewersForAt: CURR_REVIEWER_FOR_AT
        - name: notify
          image: tencentcom/wecom-message
          settings:
            msgType: markdown
            robot: "your-robot-key"
            content: |
              > ${CURR_REVIEWER_FOR_AT}
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              > from ${CNB_BUILD_USER}

评审通过后自动合并并通知

.cnb.yml
main:
  review:
    - stages:
        - name: CR 通过后自动合并
          type: git:auto-merge
          options:
            mergeType: squash
            removeSourceBranch: true
          exports:
            reviewedBy: REVIEWED_BY
        - name: notify
          image: tencentcom/wecom-message
          settings:
            msgType: markdown
            robot: "your-robot-key"
            content: |
              > CR 通过后自动合并 <@${CNB_BUILD_USER}>
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              > ${REVIEWED_BY}

release

git:release

仓库发布 Release

适用事件

push
commit.add
branch.create
tag_push
pull_request.merged
api_trigger
web_trigger
tag_deploy

参数

提示

该内置任务不支持上传附件，可使用 cnbcool/attachments 任务上传附件。

overlying

type: Boolean
required: false
default: false

叠加模式

true：叠加模式，即本次仅为编辑或更新 Release。
false：非叠加模式，即先删除，再重新创建 Release。

注意

默认为 false，即，当 Release 版本已经存在时，会先删除这个版本，重新生成。

title

type: String | Number
required: false
default: tag 名

Release 的标题

description

type: String
required: false

Release 的描述。 当内容过多时，建议使用 descriptionFromFile 参数，将内容通过文件传递，避免超出限制。

注意

description 和 descriptionFromFile 互斥，不能同时指定。

descriptionFromFile

type: String
required: false

从文件中读取内容作为 Release 的描述。

指定一个本地文件路径，系统会读取该文件的内容，然后将其作为 Release 的描述。

注意

description 和 descriptionFromFile 互斥，不能同时指定。

preRelease

type: Boolean
required: false
default: false

是否将 release 设置为预发布

latest

type: "true" | "false" | true | false
required: false
default: false

是否将 Release 设置为最新版本

配置样例

生成 changelog 并自动更新 Release 描述

.cnb.yml
$:
  tag_push:
    - stages:
        - name: changelog
          image: cnbcool/changelog
          settings:
            latestChangeLogTarget: LATEST_CHANGELOG.md
        - name: upload release
          type: git:release
          options:
            title: release
            descriptionFromFile: LATEST_CHANGELOG.md

主分支 push 时发布 Release

.cnb.yml
main:
  push:
    - stages:
        - name: git release
          type: git:release
          options:
            tag: Nightly
            description: description

pr-commit-message-preset

git:pr-commit-message-preset

预先设置 PR 的提交信息。

当用户在 PR 界面中选择 Merge 或者 Squash 合并时，会自动将该 message 填入提交消息内。

适用事件

pull_request
pull_request.target
pull_request.update
pull_request.mergeable
pull_request.approved
pull_request.changes_requested

参数

message

message

type: String
required: true

预先设置的 PR 的提交信息。

配置样例

.cnb.yml
main:
  pull_request:
    - stages:
        - name: prepare pull request commit message
          type: git:pr-commit-message-preset
          options:
            message: Pull request commit message set by CI.

pr-update

git:pr-update

更新 PR 的标签、标题。

PR 获取方式

1. 当传入 fromFile 或 fromText 参数时：

从传入的文本文件或文本中解析获取。fromFile 优先级高于 fromText。

2. 当未传入 fromFile 或 fromText 参数时：

PR 相关事件：
从该 PR 的 commits 的提交日志中解析获取。同时追加当前 PR。
commit.add 事件：
从新增 commits 的提交日志中解析获取。
非新建分支的 push 事件：
从本次推送 commits 的提交日志中解析获取。
其他情况：
从最新 commit 的提交日志中解析获取。

提示

如果需要在 branch.delete 事件中使用，由于分支已删除，无法从上下文中获取，需要使用 fromText 或者 fromFile 参数提供解析内容。

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

PR-URL: <your-repo-slug>#<number>
PR-URL: #<number>

your-repo-slug 为仓库的路径，比如 cnbcool/cnb。 number 为 PR 的编号，为 PR 页面地址后的数字。

为了和 Issue 区分，需要在前面加上 PR-URL:。

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

参数

fromText

type: String
required: false

从给定的文本中解析 PR。

不声明时，自动从上下文里的提交记录解析。可以指定一个包含 PR ID 引用的文本来声明操作对象，比如配合变更日志生成插件一起使用，将变更日志中的 PR ID 自动提取出来。

fromFile

type: String
required: false

从文本文件中读取内容并解析 PR。优先级高于 fromText。

label

type: UpdateLabel
required: false

需要添加、删除的标签。

defaultColor

type: String
required: false

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

输出结果

{
    pullRequests // 修改的 pr 列表
}

权限检查

若需要更新的 PR 属于流水线所属仓库，且非 pull_request, pull_request.update, pull_request.approved, pull_request.changes_requested 事件，则不会检查流水线触发者是否拥有修改 PR 的权限。

配置样例

如下流水线实现了以下功能：

pull_request 流水线失败，增加标签 待修改。
pull_request 流水线成功，增加标签 待评审，删除标签 待修改。
pull_request.merged 流水线，增加标签 待发布，删除标签 待评审。

.cnb.yml
main:
  pull_request:
    - stages:
        - name: check
          script: echo "do some check"
        - name: 添加PR标签-待评审
          type: git:pr-update
          options:
            label:
              add:
                - 待评审
              remove:
                - 待修改
      failStages:
        - name: 添加PR标签-待修改
          type: git:pr-update
          options:
            label:
              add:
                - 待修改

  pull_request.merged:
    - stages:
        - name: check
          script: echo "do some check"
        - name: 添加PR标签-待发布
          type: git:pr-update
          options:
            label:
              add:
                - 待发布
              remove:
                - 待评审

testing

coverage

testing:coverage

单测覆盖率，通过单测结果报告，计算单测覆盖率结果，并上报徽章数据。

可以在仓库的 洞察 页面以图表的形式按分支查看最近 100 个 Commit 的覆盖率徽章数据上报结果。

提示

Pull Request 相关事件（除了 pull_request.merged）触发的流水线报告的覆盖率数据，要查看单元测试洞察曲线，需要切换到合并请求视图。

全量覆盖率

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

json(js)（推荐使用）
json-summary
lcov（推荐使用）
jacoco
golang

参数

key

type: String
required: false

覆盖率数据 key 值，用于区分不同类型的覆盖率数据，例如 frontend、backend 等。如果仓库仅包含一种覆盖率数据，则可以忽略此参数。

name

type: String
required: false

覆盖率数据名称，用于展示在徽章中，和覆盖率数据 key 一一对应，key 不存在时，name 将被忽略。

例如：key: frontend, name: 前端覆盖率

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

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

输出结果

{
  // 代码行覆盖率，例如 100，计算出错时值为 NA
  "lines": 100,
  // 代码增量行覆盖率，例如 100，计算出错时值为 NA
  "diff_pct": 100
}

配置样例

.cnb.yml
main:
  push:
    - stages:
        - name: coverage
          type: testing:coverage
          options:
            breakIfNoCoverage: false
          exports:
            lines: LINES
        - name: result
          script: echo $LINES

artifact

remove-tag

artifact:remove-tag

删除 CNB 制品标签，目前仅删除支持 CNB Docker 和 Helm 标签。需要有仓库写权限。

适用事件

push
commit.add
tag_push
tag_deploy
pull_request.merged
api_trigger
web_trigger
crontab
branch.create

参数

type

type: String
required: false
default: docker

制品类型，目前仅支持 Docker 和 Helm

配置样例

.cnb.yml
main:
  push:
    - stages:
        - name: remove tag
          type: artifact:remove-tag
          options:
            # 包名
            # 包名示例1，仓库同名制品：reponame
            # 包名示例2，仓库非同名制品：reponame/name
            name: reponame/name
            tags:
              - tag1
              - tag2
            type: docker

tapd

在代码提交时，您可以在提交信息或PR 描述中添加 TAPD 源码关键字，云原生构建系统将自动识别并关联 Commits、PR 和 TAPD 工作项。

在代码推送、 PR 和 Tag 相关流水线中，可以通过以下任务更新 TAPD 关联项的信息。

前提条件

需在根组织中启用 TAPD 功能。
流水线触发者需绑定 TAPD 账号。

TAPD 关联项筛选规则

流水线将根据以下规则筛选关联的 TAPD 工作项：

1. 当传入 fromFile 或 fromText 参数时：

从传入的文本文件或文本中解析出 commit IDs，并查询其关联的 TAPD 工作项。

fromFile 优先级高于 fromText。

2. 当未传入 fromFile 或 fromText 参数时：

PR 相关事件：
查询该 PR 的 commits 以及 PR 描述中关联的 TAPD 工作项。
commit.add 事件：
查询新增 commits 关联的 TAPD 工作项。
非新建分支的 push 事件：
从本次推送的所有 commits 的提交日志中获取关联的 TAPD 工作项。
其他情况：
查询最新 commit 所关联的 TAPD 工作项。

通过以上规则，确保代码变更与 TAPD 工作项的系统化、高效关联。

TAPD 关联项类型

TAPD 工作项 源码关键字 中的类型即为工作项类型，如：story、task、bug。

需要注意的是，TAPD 任务的源码关键字可能为 story 或 task，请注意区分。

status-update

tapd:status-update

更新 tapd 关联项（story、task 或 bug）状态

参数

when

type: String | Array<String>
required: false

更新指定状态的工作项，为空时不做过滤。

type

Enum<String>: story | task | story
required: false

更新指定类型的工作项，为空时不做过滤。

fromText

type: String
required: false

从文本中解析出 commit id，查询其关联的工作项。

fromFile

type: String
required: false

从文本文件中解析出 commit id，查询其关联的工作项。

配置样例

对所有 TAPD 关联项进行状态扭转

.cnb.yml
main:
  push:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: 进行中

对符合条件的 TAPD 关联项进行状态扭转

.cnb.yml
main:
  pull_request.merged:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: 已完成
            when:
              - 进行中
            type: story

从 fromText 中解析 commit id，查询 TAPD 关联项进行状态扭转

.cnb.yml
$:
  tag_push:
    - stages:
        - name: 生成 changelog
          image: cnbcool/changelog
          settings:
            dryRun: true
            linkReferences: false
          exports:
            latestChangeLog: RELEASE_NOTES
        - name: tapd
          type: tapd:status-update
          options:
            status: 已发布
            type: story
            fromText: $RELEASE_NOTES

comment

tapd:comment

提交 tapd 关联项（story、task 或 bug）评论

参数

when

type: String | Array<String>
required: false

对符合指定状态的工作项进行评论，为空时不做过滤。

type

Enum<String>: story | task | story
required: false

对符合指定类型的工作项进行评论，为空时不做过滤。

fromText

type: String
required: false

从文本中解析出 commit id（最多 50 个），查询其关联的工作项。

fromFile

type: String
required: false

从文本文件中解析出 commit id，查询其关联的工作项。

配置样例

对所有 TAPD 关联项进行评论：

.cnb.yml
main:
  push:
    - stages:
        - name: add tapd comment
          type: tapd:comment
          options:
            comment: 开始开发

对符合条件的 TAPD 关联项进行评论：

.cnb.yml
main:
  pull_request.merged:
    - stages:
        - name: add tapd comment
          type: tapd:comment
          options:
            comment: 已合并
            when:
              - 进行中
            type: story

从 fromText 中解析 commit id，查询 TAPD 关联项进行评论

.cnb.yml
$:
  tag_push:
    - stages:
        - name: 生成 changelog
          image: cnbcool/changelog
          settings:
            dryRun: true
            linkReferences: false
          exports:
            latestChangeLog: RELEASE_NOTES
        - name: tapd
          type: tapd:comment
          options:
            comment: 已发布
            type: story
            fromText: $RELEASE_NOTES

knowledge

update

knowledge:update

更新知识库，用于把 Issue、仓库文档等构建进入知识库。

参数

include

type: String | Array<String>
required: false
default: **/**.md

指定需要包含的文件，使用 Glob 模式匹配，默认为 **/**.md（包含所有 Markdown 文件），支持数组或逗号分隔。当前支持的文件类型有：.md、.mdx、.docx、.txt、.pdf。

exclude

type: String | Array<String>
required: false

指定需要排除的文件，使用 Glob 模式匹配，默认不排除任何文件，支持数组或逗号分隔。

chunkSize

type: Number
required: false
default: 1500

指定文本分块大小。

chunkOverlap

type: Number
required: false
default: 0

指定相邻两个分块之间的重叠 token 数量。

embeddingModel

type: String
required: false
default: hunyuan

嵌入模型，目前仅支持 hunyuan。

issueSyncEnabled

type: Boolean
required: false
default: true

是否启用 Issue 同步功能。启用后会自动拉取仓库的 Issue 数据并加入知识库。

issueState

type: String
required: false

仅同步指定状态的 Issue，默认包含全部 Issue，可选值为 open | closed。

issueLabels

type: String | Array<String>
required: false

仅同步指定标签的 Issue，默认包含全部 Issue，支持数组或逗号分隔。

issueExcludeLabels

type: String | Array<String>
required: false

排除带有指定标签的 Issue，默认不排除任何 Issue，支持数组或逗号分隔。当与 issueLabels 存在交集时，exclude 优先。

forceRebuild

type: Boolean
required: false
default: false

是否删除知识库并重新构建。当设置为 true 时，删除并重新创建知识库。

ignoreProcessFailures

type: Boolean
required: false
default: false

是否忽略文档处理失败。当设置为 true 时，即使有文件处理失败也会更新知识库。

配置样例

基本使用

.cnb.yml
main:
  push:
    - stages:
        - name: build knowledge base
          type: knowledge:update
          options:
            include: "**/**.md"

npc

go

npc:go

在指定的 Docker 镜像中执行 AI 任务。

在 Issue 或 PR 评论中 @NPC 角色会使用内置的 system/user prompt；其他事件下，可通过 systemPrompt、userPrompt、role 参数自定义提示词。

可以在镜像中安装 NPC 运行时需要 CLI 工具和 Skills ，例如使用 CNB Skill。更多 NPC 相关配置，请查阅 NPC 事件。

参数

注意

role、systemPrompt、userPrompt 在 issue.comment@npc、pull_request.comment@npc 事件中会被自动忽略，无需配置。

通过 API 触发 api_trigger 构建时，即使请求体传入 npc.name=CodeBuddy， npc:go 仍按非 NPC 事件处理：systemPrompt / userPrompt 需要从本步骤的 options 中传入； role 如有配置，仍会按 .cnb/settings.yml 中的 NPC 角色解析并拼接到 system prompt。请求体中的 npc 字段只影响流水线身份、CNB_TOKEN 权限、计费口径与标题等运行上下文，不会替代 npc:go 的 role 参数。

role

type: String
required: false

NPC 角色名称，需要在 .cnb/settings.yml 文件中的 NPC 的 roles 字段中定义，可以参考 UI 定制（在新窗口打开）。

systemPrompt

type: String
required: true

NPC 系统提示词。

userPrompt

type: String
required: true

NPC 用户输入，主要用于用户向 NPC 描述任务。

maxTurns

type: Number
required: false

Agent 最大对话轮次。所有事件下均生效，达到上限时 Agent 会被中止，输出可能不完整。

model

type: String
required: false

Agent 使用的模型 ID。不指定时使用平台默认模型，所有事件下均生效。

contextWindow

type: String | Number
required: false

模型上下文窗口大小，支持以下写法：

带小写单位："128k"（k = 1000）或 "1m"（m = 1000000）
纯数字：128000 或 "128000"

取值范围为 128k ~ 1m（即 128000 ~ 1000000 tokens），越界或格式不合法（如大写、带小数、带空白）会直接报错。不指定时使用平台默认值，所有事件下均生效。用于上下文超限时触发自动摘要压缩，需与所选 model 实际支持的上下文窗口保持一致。

环境变量

npc:go 能读到当前流水线的环境变量，包括平台内置环境变量、流水线 / Stage / Job 三层的 env 与 imports，以及上游 Job 的 exports。

注意

npc:go 可能将读到的环境变量输出到 Issue / PR 评论区。在 issue.comment@npc、pull_request.comment@npc 等不可信事件下，请避免让敏感值进入 npc:go 的环境变量。

输出结果

{
  // NPC 最后一条 assistant 消息的文本内容
  "result": "..."
}

配置样例

1. NPC 事件流水线：在 issue.comment@npc 事件中调用 npc:go，镜像需包含 NPC 运行时需要的 CLI 工具和 Skills（镜像构建见下方第 2 步）：

.cnb.yml
$:
  issue.comment@npc:
    - docker:
        # 指定镜像，内含 NPC 运行时需要的 CLI 工具和 Skills
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

2. 构建并推送 NPC 镜像：将镜像推送到制品库后，供上方 NPC 事件流水线使用：

.cnb.yml
main:
  push:
    - services:
        - docker
      stages:
        - name: Docker build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: Docker push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

在 Dockerfile 中，需要安装 NPC 运行时需要的 Skills 和 CLI 工具。例如，下面的示例安装了 cnb-skill 和 cnb-cli 工具。

Dockerfile
FROM node:22-bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates git git-lfs curl jq ripgrep \
    && rm -rf /var/lib/apt/lists/* \
    && git lfs install \
    && npm install -g @cnbcool/cnb-cli skills \
    && npx skills add https://cnb.cool/cnb/skills/cnb-skill.git -g -y

Skills 支持自动加载以下目录： ~/.agents/skills、~/.codebuddy/skills 以及对应的项目目录：.agents/skills、.codebuddy/skills。

项目级 Skills 优先级高于用户级，同名 Skill 项目级会覆盖用户级。

NPC 角色的 prompt 定义在 .cnb/settings.yml 文件中，请查阅 NPC 事件。