CNB 文档

简体中文

English

简体中文

English

外观

内置任务

复制页面

14460 字约 48 分钟

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

总览

  • docker:
    • cache: 构建 Docker 镜像缓存，加速依赖安装
  • cnb:
  • vscode:
    • go: 控制云原生开发环境可用时机
  • git:
  • testing:
  • artifact
  • 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

参见 await-resolve

resolve

参见 await-resolve

await-resolve

  • cnb:await
  • cnb:resolve

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

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

提示

await-resolve 同 apply、trigger 的区别：

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

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

使用限制

  1. 只能对 同一个事件 触发的 pipeline 进行 await 和 resolve 操作
  2. 一个 key 仅能 resolve 一次，但可以 await 多次
  3. 通过 key 对 await 和 resolve 进行分组
  4. 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 参数

key
  • type: String
  • required: true

配对 ID

resolve 参数
key
  • type: String
  • required: true

配对 ID

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

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

title
  • type: String
  • required: 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 取值优先级

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

  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，远程文件可先自行下到本地。

输出结果

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

配置样例

.cnb.yml
main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            configFrom: ./test/.cnb.yml
            event: api_trigger_test
.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

个人访问令牌。

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

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

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

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

  • 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

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

title
  • type: String
  • required: 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 结构）。

适用事件

所有事件

参数

filePath
  • type: String
  • required: true

本地文件路径。

输出结果

{
  // 读到的对象
}

配置样例

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

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 事件触发条件和时机参考事件。

适用事件

pull_request.mergeable

参数

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

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

mergeCommitMessage
  • type: String
  • required: false

合并点提交信息。

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

  2. 当合并策略为 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
  1. 当合并策略为 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
  1. 也可以直接指定

如通过环境变量指定为当前 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 群交叉走查自动合并
  1. 走查通过后自动合并
  2. 记录走查者信息在提交信息中
.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

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

label

对 label 的操作描述。

assignee

对 处理人 的操作描述。

when

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

lint

检查 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

类型定义
IssueStateMap
  • Enum<String>: open | close
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

操作类型：

  • 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 为 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

评审人或处理人可以添加的角色可选包括：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 版本已经存在时，会先删除这个版本，重新生成。

tag
  • type: String | Number
  • required: false

release 对应的 Tag 名，非必填

tag_push 事件无需传入，直接取触发 tag_push 事件的 Tag 名。

非 tag_push 事件必填，用来作为 Release 对应的 Tag 名。

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
  • 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

需要添加、删除的标签。

title
  • type: String
  • required: false

PR 的标题。

defaultColor
  • type: String
  • required: false

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

输出结果

{
    pullRequests // 修改的 pr 列表
}

权限检查

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

配置样例

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

  1. pull_request 流水线失败，增加标签 待修改。
  2. pull_request 流水线成功，增加标签 待评审，删除标签 待修改。
  3. 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）触发的流水线上传的覆盖率数据， 要查看单元测试洞察曲线，需要切换到合并请求视图。

适用事件

所有事件

全量覆盖率

coveragecoveragecoveragecoverage

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

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

增量覆盖率

coverage-prcoverage-prcoverage-prcoverage-pr

参数

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

参数

name
  • type: String
  • required: true

制品包名

tags
  • type: Array<string>
  • required: true
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）状态

适用事件

所有事件

参数

status
  • type: String
  • required: true

目标状态。

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，查询其关联的工作项。

配置样例

  1. 对所有 TAPD 关联项进行状态扭转
.cnb.yml
main:
  push:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: 进行中
  1. 对符合条件的 TAPD 关联项进行状态扭转
.cnb.yml
main:
  pull_request.merged:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: 已完成
            when:
              - 进行中
            type: story
  1. 从 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）评论

适用事件

所有事件

参数

comment
  • type: String
  • required: true

评论内容。

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，查询其关联的工作项。

配置样例

  1. 对所有 TAPD 关联项进行评论：
.cnb.yml
main:
  push:
    - stages:
        - name: add tapd comment
          type: tapd:comment
          options:
            comment: 开始开发
  1. 对符合条件的 TAPD 关联项进行评论：
.cnb.yml
main:
  pull_request.merged:
    - stages:
        - name: add tapd comment
          type: tapd:comment
          options:
            comment: 已合并
            when:
              - 进行中
            type: story
  1. 从 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、仓库文档等构建进入知识库。

适用事件

所有事件

工作机制

拉取仓库的 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 最后一条 assistant 消息的文本内容
  "result": "..."
}

配置样例

.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

# 构建并推送 Docker 镜像
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 事件。

© 2026 cnb.cool