Built-in Missions

About 8188 wordsAbout 27 min

In each stage operation, in addition to using custom Missions, CNB also extends some commonly used built-in Missions for developers to use.

Docker

cache

docker:cache

Docker Cache, builds a Docker image as cache for reuse in future builds.

Can avoid repeated downloads of network resources such as dependencies.

Parameters

dockerfile

type: String
required: true

Path to Dockerfile for building cache image.

To avoid excessively long builds, Docker image build timeout is controlled by job.timeout parameter.

by

type: Array<String> | String
required: false

Declares the list of files that the cache image build depends on. Note: Files not in the by list, except Dockerfile, will be treated as non-existent during image build.

Supports array format
Supports string format with multiple files separated by commas

versionBy

type: Array<String> | String
required: false

Used for version control. If versionBy is not provided, defaults to by value for version control.

When content of files pointed by versionBy changes, it will be considered a new version. The specific calculation logic is: sha1(Dockerfile + versionBy + buildArgs + target + arch).

Supports array format
Supports string format with multiple files separated by commas

buildArgs

type: Object
required: false

Inserts additional build parameters during build (--build-arg $key=$value). When value is null, only adds key (--build-arg $key).

target

type: String
required: false

Corresponds to --target parameter in docker build, allowing selective building of specific stages in Dockerfile rather than the entire Dockerfile.

sync

type: Boolean
required: false
default: false

Whether in sync mode, waits for cache image docker push to succeed before continuing.

ignoreBuildArgsInVersion

type: Boolean
required: false
default: false

Whether to ignore buildArgs in version calculation.

See Version Control

Output

{
  // Docker image name corresponding to cache
  name
}

Configuration Examples

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

Here, cache.dockerfile is a Dockerfile for building cache images. Example:

# Select a Base image
FROM node:14

# Set working directory
WORKDIR /space

# COPY files listed in by
COPY . .

# Install dependencies based on COPIED files
RUN npm ci

# Set required environment variables
ENV NODE_PATH=/space/node_modules

cnb

await-resolve

cnb:await
cnb:resolve

await waits for resolve execution, resolve can pass variables to await.

Through await-resolve, multiple concurrent pipelines can coordinate with each other to achieve more flexible sequence control.

Tips

Difference between await-resolve and apply, trigger:

The former means when a pipeline in a build executes to await task, it waits for resolve notification of corresponding key to continue.

The latter means a pipeline triggers new events to start new builds. Can cross repositories. Can be called asynchronously or wait synchronously.

Usage Limitations

Can only perform await and resolve operations on pipelines triggered by the same event
A key can only be resolved once, but can be awaited multiple times
Group await and resolve by key

Deadlock Detection

await and resolve can work together to achieve flexible process control, but also introduce more complex edge cases, such as:

pipeline-1 and pipeline-2 await each other, i.e. deadlock
Multiple pipelines form an await loop, i.e. indirect deadlock
await a non-existent key, or key has no associated resolve, i.e. infinite wait
resolve's pipeline execution fails, corresponding await falls into infinite wait
Multiple resolve tasks associate with same key, i.e. duplicate resolve throws exception

Deadlock Detection mechanism automatically detects above exceptions, ends await wait state, throws dead lock found. exception.

Order of await and resolve in config file does not affect execution results, i.e. final await task will always wait for corresponding resolve to complete, this case won't be terminated by Deadlock Detection mechanism.

Applicable Events

All Events

await Parameters

key

type: String
required: true

Pairing ID

resolve Parameters

key

type: String
required: true

Pairing ID

data

type: object
required: false

Object to pass

key: value format, supports multiple levels. Example:

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

Result of await task is data object declared by resolve. Can access this object through exports, example:

- 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

Of course, can also not pass any content, just represent a wait action:

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

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

Output

{
  // data content returned by resolve
  data
}

apply

cnb:apply

适用事件

push
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 取值优先级

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

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

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

输出结果

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

配置样例

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

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

            event: api_trigger_test

main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            # 执行当前配置文件的其它事件
            event: api_trigger_test
  api_trigger_test:
    - stages:
        - name: test
          script: echo test

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

read-file

cnb:read-file

Reads file content and parses it for subsequent tasks.

Using ##[set-output key=value] directive is more convenient for outputting variables, but will expose content in logs, which is not suitable for sensitive information.

For pre-determined sensitive information, use imports. For sensitive information generated during build process, write to file and read with this built-in task.

imports only supports files existing in remote repositories, while this built-in task only supports reading local files.

File type is determined by extension, currently supports json, yml(yaml), and plain text (key=value structure).

Applicable Events

All Events

Parameters

filePath

type: String
required: true

Local file path

Output

{
  // The read object
}

Configuration Examples

Write variables needed by subsequent tasks to file, then read file with this built-in task to export as environment variables for use by subsequent tasks.

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 #Specify multi-level key
            $myKey.myVar: ENV_ENV_KEY_MY_VAR #Use environment variable to specify key
        - name: echo env
          script:
            - echo $ENV_MY_VAR
            - echo $ENV_DEEP_MY_VAR
            - echo $ENV_ENV_KEY_MY_VAR

trigger

cnb:trigger

Triggers a custom event pipeline in another repository from the current repository.

Applicable Events

All Events

Parameters

token

type: String
required: true

Personal access token.

The new pipeline will be triggered by the token's corresponding user, and will check if the user has permission to access the target repository.

slug

type: String
required: true

Full path of target repository, e.g.: group/repo.

event

type: String
required: true

Custom event name to trigger, must be api_trigger or start with api_trigger_.

The target repository must have configured the corresponding event pipeline to be triggered.

branch

type: String
required: false

Trigger branch, defaults to main branch.

sha

type: String
required: false

CommitId in trigger branch, defaults to latest commit record of branch.

env

type: TriggerEnv
required: false

Environment variables when triggering target repository pipeline.

Default values include following environment variables which users cannot override:

API_TRIGGER_BUILD_ID, same meaning as CNB_BUILD_ID in CI default environment variables
API_TRIGGER_PIPELINE_ID, same meaning as CNB_PIPELINE_ID in CI default environment variables
API_TRIGGER_REPO_SLUG, same meaning as CNB_REPO_SLUG in CI default environment variables
API_TRIGGER_REPO_ID, same meaning as CNB_REPO_ID in CI default environment variables
API_TRIGGER_USER, same meaning as CNB_BUILD_USER in CI default environment variables
API_TRIGGER_BRANCH, same meaning as CNB_BRANCH in CI default environment variables
API_TRIGGER_COMMIT, same meaning as CNB_COMMIT in CI default environment variables
API_TRIGGER_COMMIT_SHORT, same meaning as CNB_COMMIT_SHORT in CI default environment variables

sync

type: Boolean
required: false
default: false

Whether to execute synchronously. In sync mode, will wait for current trigger pipeline to succeed before executing next task.

continueOnBuildError

type: Boolean
required: false
default: false

In sync mode, whether to continue next task when triggered pipeline build fails.

title

type: String
required: false

Custom pipeline title

Type Definitions

TriggerEnv

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

Output

{
  "sn": "cnb-i5o-1ht8e12hi", // Build number
  "buildLogUrl": "http://xxx/my-group/my-repo/-/build/logs/cnb-i5o-1ht8e12hi", // Build log URL
  "message": "success",
  "buildSuccess": true, // Whether triggered build succeeded, this key only exists in sync mode
  "lastJobExports": {} // Environment variables exported by last job of triggered pipeline
}

Configuration Examples

Basic Usage

Trigger a pipeline with event name api_trigger_test in another repository's main branch from current repository.

The pipeline configuration uses the .cnb.yml file from the target repository's main branch.

Use access token $TOKEN to check if user has repository permission.

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

vscode

go

vscode:go

The difference between configuring this built-in task in remote development:

With this task: When starting Cloud Native Development, need to wait for this task to complete before WebIDE and VSCode/Cursor client entries appear.
Without this task: After pipeline prepare phase completes (code-server service starts), WebIDE and VSCode/Cursor client entries will appear before stages tasks execute.

The difference in entry appearance timing: Only refers to the timing from loading wait page to entry selection page. Actually, whether using this task or not, remote development is already available after code-server service starts.

Note: Using this task will increase wait time. If you need to delay developer entry timing, allowing entry only after certain tasks complete, you can use this task.

Applicable Events

vscode
branch.create
api_trigger
web_trigger

Output

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

Configuration Examples

.cnb.yml
$:
  # vscode event: specifically for launching remote development from page
  vscode:
    - docker:
        # Use custom image as development environment, if not provided, will use default image cnbcool/default-dev-env:latest
        image: cnbcool/default-dev-env:latest
      services:
        - vscode
        - docker
      stages:
        # Want to wait for this task to complete before entering development environment
        - name: ls
          script: ls -al
        - name: vscode go
          type: vscode:go
        # Tasks that can execute after entering development environment
        - name: ls
          script: ls -al

git

auto-merge

git:auto-merge

Automatically merge Pull Request, typically used after PR passes pull_request pipeline checks and Code Review, automatically merges PR in pull_request.mergeable pipeline. No manual merge button click required.

For pull_request.mergeable event trigger conditions and timing, refer to Events.

Applicable Events

pull_request.mergeable

Parameters

mergeType

type: String
required: false
default: auto

Merge strategy, defaults to auto: if multiple commits use merge, otherwise use squash.

mergeCommitMessage

type: String
required: false
Merge commit message.

When merge strategy is rebase, this message is invalid and not needed.

When merge strategy is merge, defaults to chore: merge node(merged by CNB), automatically appends PR reference, reviewers list, and PR committers list. Example:

chore: merge node(merged by CNB)

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

When merge strategy is squash, defaults to the PR's first commit message. Automatically appends PR reference, reviewers list, and PR committers list. Example:

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

This configuration produces the following effect:

A PR (feat/model-a -> main) has two commits:

Commit 1, submitted on 2023-10-1:

feat(model-a): Add new feature for module A

For some reason, add some feature

close #10

Commit 2, fixes issues pointed out during CR, submitted on 2023-10-2:

fix(model-a): Fix issues pointed out in review

After auto merge, this commit node will be created on main branch, meaning subsequent commits (commit 2) will be removed:

feat(model-a): Add new feature for module A

For some reason, add some feature

close #10

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

mergeCommitFooter

type: String
required: false

Footnotes to add to merge commit, multiple footnotes separated by \n, only effective for merge and squash.

When merge strategy is rebase, this is invalid and not needed.

When merge strategy is merge or squash, adds the input as lines to footer, then appends PR reference, reviewers list, and PR committers list. Example:

.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

Whether to delete source branch after merge.

Invalid when source and target branches are in different repositories.

ignoreAssignee

type: Boolean
required: false
default: false

Whether to ignore assignee.

When PR has specified assignee, this task won't execute auto merge logic, because assignee means assigning someone to handle manually.

When true, can force merge ignoring assignee.

Output

{
    reviewedBy, // String, committer info appended to commit message
    reviewers, // Array<String>, list of reviewers
}

Configuration Examples

Standalone Usage

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

When a PR on branch main triggers pull_request.mergeable event, this PR will be automatically merged using merge strategy.

Used with Target Branch's Push Event

.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

When a PR on branch main triggers pull_request.mergeable event, this PR will be automatically merged using merge strategy. After auto merge, it will trigger push event on target branch (main), continuing with declared build and publish processes.

Regarding responsibility for resulting push event processes, the rules are:

If PR submitter is a member of target repository, they are responsible for subsequent push event processes (push build pipeline will be sent to them).
If PR submitter is not a member of target repository (e.g. PR from Forked Repo in open source projects), the last Code Review Reviewer will be responsible for subsequent push event processes.

最佳实践

使用 squash 自动合并

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

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

使用 auto 自动选择合并类型

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

.cnb.yml
master:
  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

Update Issue Status, close or open Issue, modify Issue labels.

Applicable Events

All Events

工作机制

查找 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 之间加上一个空行

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

cnb/feedback#123"

方法二：

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

git 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
- 要添加的标签列表，标签不存在时，会自动创建。
remove
- type: Array<String> | String
- required: false
- 要移除的标签列表

IssueUpdateStatus

label
- type: Array<String> | String
- required: false
- 标签，多个值之间是 or 关系

输出结果

{
    issues // 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
            # 移除 “预发布” 标签，添加 “已发布” 标签
            label:
              add: 已发布
              remove: 预发布
            # 当有 “feature” 或 “bug” 标签才进行上述操作
            when:
              label:
                - feature
                - bug

根据 changelog 添加标签

.cnb.yml
$:
  tag_push:
    - stages:
        - name: changelog
          image: cnbcool/changelog
          exports:
            latestChangeLog: LATEST_CHANGE_LOG
        - name: update issue
          type: git:issue-update
          options:
            fromText: ${LATEST_CHANGE_LOG}
            label:
              add: 需求已接收
            when:
              label: feature

reviewer

git:reviewer

配置评审人给 PR 添加评审人。

适用事件

pull_request
pull_request.target
pull_request.update

参数

type

type: REVIEW_OPERATION_TYPE
required: false
default: add-reviewer

操作类型：

add-reviewer：添加 reviewer，添加 reviewers 参数传入的成员
add-reviewer-from-repo-members：从仓库直接成员里选一名，添加为 reviewer
add-reviewer-from-group-members：从仓库父组织（直接上级组织）里选一名，添加为 reviewer
add-reviewer-from-outside-collaborator-members：从仓库的外部协作者里选一名，添加为 reviewer
remove-reviewer：从已有的 reviewer 中删除指定的成员

reviewers

type: Array<String> | String
required: false

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

type 为 add-reviewer、remove-reviewer 时必填。

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

count

type: Number
required: false

指定要添加的 reviewer 数量，随机抽取。

当 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

如果已有 reviewer 的数量 <count，那么补齐。

如果已有 reviewer 的数量 >=count，那么什么也不做。

exclude

type: Array<String> | String
required: false

排除指定的用户。

reviewersConfig

type: IReviewersConfig | String
required: false

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

type 为 add-reviewer 时有效。

支持两种格式：

字符串格式，传入配置文件相对路径(支持 json 文件)：

reviewersConfig: config.json

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

对象格式，传入文件评审人配置：

reviewersConfig:
  ./src: name1,name2
  .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

IReviewersConfig

{
    [key: String]: String
}

ROLE_TYPE

Enum<String>

Developer | Master | Owner

输出结果

{
    // 当前有效的 reviewers
    reviewers,

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

配置样例

添加评审人

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

删除指定成员

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

结合 ifModify，指定文件被修改时添加 reviewer

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

结合 if，在指定条件下将某些人添加为 reviewer

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

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

.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}

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

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

最佳实践

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

PR 随机选择N名评审者，通知到群
评审通过后自动合并
记录评审者信息在提交信息中
Git 设置满足多人评审自动合并策略实现多人交叉评审

.cnb.yml
main:
  review:
    - stages:
        - name: CR 通过后自动合并
          type: git:auto-merge
          options:
            mergeType: squash
            removeSourceBranch: true
            mergeCommitMessage: $CNB_LATEST_COMMIT_MESSAGE
          exports:
            reviewedBy: REVIEWED_BY
        # 将评审消息发送到企业微信机器人
        - name: notify
          image: tencentcom/wecom-message
          settings:
            msgType: markdown
            robot: "155af237-6041-4125-9340-000000000000"
            content: |
              > CR 通过后自动合并 <@${CNB_BUILD_USER}> 
              > 　
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              > 
              > ${REVIEWED_BY}

  pull_request:
    - stages:
        # ...省略其它任务

        # 发送到 CR 专用群
        - 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: "155af237-6041-4125-9340-000000000000"
            message: |
              > ${CURR_REVIEWER_FOR_AT}
              > 　
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              > 　
              > from ${CNB_BUILD_USER}

release

git:release

仓库发布 Release

适用事件

push
branch.create
tag_push
pull_request.merged
api_trigger
web_trigger
tag_deploy

参数

overlying

type: Boolean
required: false
default: false

叠加模式

true：叠加模式，同一个 release 可以提交多次，最终的 release 是多次提交的并集。如果同名附件已经存在，会先删除再上传，达到更新的效果。
false：非叠加模式，以最后一个提交的为准，前面的会被清除。

Warning

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

title

type: String
required: false
default: tag 名

release 的标题

description

type: String
required: false

release 的描述

preRelease

type: Boolean
required: false
default: false

是否将 release 设置为预发布

latest

type: String
required: false
default: false

是否将 release 设置为最新版本

输出结果

无

配置样例

生成 changelog 并自动更新 release 描述

.cnb.yml
$:
  tag_push:
    - stages:
        - name: changelog
          image: cnbcool/changelog
          exports:
            latestChangeLog: LATEST_CHANGE_LOG
        - name: upload release
          type: git:release
          options:
            title: release
            description: ${LATEST_CHANGE_LOG}

主分支 push 时发布 release

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

testing

coverage

testing:coverage

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

适用事件

所有事件

全量覆盖率

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

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

增量覆盖率

变更行对应的单测覆盖率，仅支持 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

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

输出结果

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

配置样例

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

push
tag_push
tag_deploy
pull_request.merged
api_trigger
web_trigger
crontab

参数

name

type: 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