Built-in Plugin

About 6964 wordsAbout 23 min

In each stage operation, in addition to using custom Missions, CNB also extends some commonly used Built-in Plugin 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 supports two formats: array and string
            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
          # Copy files from cache for use
          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, web_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

Applicable Events

push
branch.create
pull_request.target
pull_request.mergeable
tag_push
pull_request.merged
api_trigger
web_trigger
crontab
tag_deploy

Parameters

config

type: String
required: false Complete CI configuration file content

configFrom

type: String
required: false Specify a local file as the configuration file.

event

type: String
required: false
default: api_trigger Custom event name to execute, must be api_trigger or start with api_trigger_.

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

sync

type: Boolean
required: false
default: false Whether to execute synchronously.

In sync mode, it will wait for this apply pipeline to succeed before executing the next task.

continueOnBuildError

type: Boolean
required: false
default: false In sync mode, whether to continue executing the next task when the triggered pipeline build fails.

title

type: String
required: false Custom pipeline title

Environment Variables

Current Job visible, business-defined environment variables are all passed to the new pipeline.

Default values include the following environment variables, users cannot override:

APPLY_TRIGGER_BUILD_ID, same meaning as CNB_BUILD_ID in CI default environment variables
APPLY_TRIGGER_PIPELINE_ID, same meaning as CNB_PIPELINE_ID in CI default environment variables
APPLY_TRIGGER_REPO_SLUG, same meaning as CNB_REPO_SLUG in CI default environment variables
APPLY_TRIGGER_REPO_ID, same meaning as CNB_REPO_ID in CI default environment variables
APPLY_TRIGGER_USER, same meaning as CNB_BUILD_USER in CI default environment variables
APPLY_TRIGGER_BRANCH, same meaning as CNB_BRANCH in CI default environment variables
APPLY_TRIGGER_COMMIT, same meaning as CNB_COMMIT in CI default environment variables
APPLY_TRIGGER_COMMIT_SHORT, same meaning as CNB_COMMIT_SHORT in CI default environment variables
APPLY_TRIGGER_ORIGIN_EVENT, same meaning as CNB_EVENT in CI default environment variables
CNB_PULL_REQUEST_ID, same meaning as CNB_PULL_REQUEST_ID in CI default environment variables
CNB_PULL_REQUEST_IID, same meaning as CNB_PULL_REQUEST_IID in CI default environment variables
CNB_PULL_REQUEST_MERGE_SHA, same meaning as CNB_PULL_REQUEST_MERGE_SHA in CI default environment variables

config Priority

Values are taken in the following order, stopping when a value is found:

config
configFrom
Current repository .cnb.yml
If apply built-in task is called in pull_request.merged event, take the merged configuration file
If apply built-in task is called in pull_request.target, pull_request.mergeable events, take the target branch's configuration file
Other cases take the current branch configuration file

configFrom only supports local files like ./test/.cnb.yml, remote files can be downloaded locally first.

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 the triggered build succeeded, this key only exists in sync mode
  "lastJobExports": {} // Environment variables exported by the last job of the triggered pipeline
}

Configuration Examples

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:
            # Execute other events of the current configuration file
            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.

Best Practices

Using Squash for Auto Merge

Using squash merge, one PR operation only generates one commit node in the target branch, and deletes the source branch if permissions allow.

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

Using Auto to Automatically Select Merge Type

If multiple people commit, use merge, otherwise use squash.

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

Establishing Dedicated CR Group for Cross-Review Auto Merge

Auto merge after review passes
Record reviewer information in commit message

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: Automatically merge after CR is passed
          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: |
              > Automatically merge after CR is passed <@${CNB_BUILD_USER}> 
              > 　
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              > 
              > ${REVIEWED_BY}

  pull_request:
    - stages:
        # ...Omit other tasks
        - 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

Work Mechanism

Find if Issue exists -> Check if it meets when conditions (optional) -> Check if it meets lint conditions (optional) -> Update issue status or labels

How to Get Issue ID

If fromText parameter is passed, extract from fromText. branch.delete must pass fromText (branch has been deleted, cannot get from context).
If fromText parameter is not passed, extract from context.
- push event: Extract from commit logs of all commits in this push.
- Merge request events: Extract from commit logs of all commits in the merge request.
- Other events: Extract from the latest commit log.

Extraction method: Extract the following two formats from the text:

#issueID: Represents an issue in the current repository. For example, #123 represents issue with ID 123 in the current repository.
groupName/repoName#issueID: Represents a cross-repository (other repository) issue. For example, test/test#123 represents issue with ID 123 in the test/test repository.

Note: #123 or test/test#123 must be preceded by a space.

How to Include Issue ID in Commit Logs

When committing code, you can add related Issue ID in the commit log. When using this built-in task, it can automatically extract the related Issue to update Issue labels and status.

It's recommended to include Issue ID in the commit log body. Here are the command line methods:

Method 1: Use shift + enter for line break, recommend adding an empty line between title and body

git commit -m "fix(Cloud Native Build): Fix an error

cnb/feedback#123"

Method 2:

The following commit method will create two line breaks between title and body

git commit -m "fix(Cloud Native Build): Fix an error" -m "cnb/feedback#123"

Parameters

fromText

type: String
required: false

Parse Issue Id from the given text.

If not declared, automatically parse from commit records in the context.

You can specify a text containing issue id references to declare the operation object, such as: ${LATEST_CHANGE_LOG}.

state

type: IssueStateMap
required: false

Corresponding to the state attribute, when set to close, the Issue can be closed.

label

type: IssueUpdateLabel
required: false

Description of operations on label.

when

type: IssueUpdateStatus
required: false

Filter conditions, multiple conditions are in or relationship. If empty, operate on all Issues.

lint

type: IssueUpdateStatus
required: false

Check if the Issue meets the conditions, throw an exception if not, multiple conditions are in or relationship, if empty, no check is performed.

defaultColor

type: String
required: false

Default color of the added label, only effective when label.add parameter is passed.

Type Definitions

IssueStateMap

Enum<String>

open | close

IssueUpdateLabel

add
- type: Array<String> | String
- required: false
- List of labels to add, if the label does not exist, it will be automatically created.
remove
- type: Array<String> | String
- required: false
- List of labels to remove

IssueUpdateStatus

label
- type: Array<String> | String
- required: false
- Labels, multiple values are in or relationship

Output

{
    issues // issue list
}

Configuration Examples

After merging to main, update labels

.cnb.yml
main:
  push:
    - stages:
        - name: update issue
          type: git:issue-update
          options:
            # Remove "In Development" label, add "Pre-release" label
            label:
              add: Pre-release
              remove: In Development
            # Only perform the above label operations when there are "feature" or "bug" labels
            when:
              label:
                - feature
                - bug

When tag_push, close issue, update labels

.cnb.yml
$:
  tag_push:
    - stages:
        - name: Publish Operation
          script: echo "Replace current task with publish task"
        # After publish operation, perform issue update operation
        - name: update issue
          type: git:issue-update
          options:
            # Close issue
            state: close
            # Remove "Pre-release" label, add "Published" label
            label:
              add: Published
              remove: Pre-release
            # Only perform the above operations when there are "feature" or "bug" labels
            when:
              label:
                - feature
                - bug

Add labels based on 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: Requirement Received
            when:
              label: feature

reviewer

git:reviewer

Configure Reviewers or Assignees Add/remove reviewers/assignees to PR, can specify alternative reviewer/assignee range.

Applicable Events

pull_request
pull_request.target
pull_request.update

Parameters

type

type: REVIEW_OPERATION_TYPE
required: false
default: add-reviewer

Operation type:

add-reviewer: Add reviewer, add members passed in the reviewers parameter
add-reviewer-from-repo-members: Select one from the repository's direct members, add as reviewer
add-reviewer-from-group-members: Select one from the repository's parent organization (direct parent organization), add as reviewer
add-reviewer-from-outside-collaborator-members: Select one from the repository's external collaborators, add as reviewer
remove-reviewer: Remove specified members from existing reviewers
add-assignee: Add assignee, add members passed in the reviewers parameter
remove-assignee: Remove specified members from existing assignees

reviewers

type: Array<String> | String
required: false

Username of the reviewer to add or remove. Multiple separated by , or ;.

Required when type is add-reviewer, remove-reviewer, add-assignee, remove-assignee.

If both reviewers and reviewersConfig are configured, randomly select the specified number of reviewers or assignees from both.

count

type: Number
required: false

Specify the number of reviewers or assignees to add, randomly selected.

When type=add-reviewer, count defaults to the number of reviewers, i.e., add all
When type=add-reviewer-from-repo-members, count defaults to 1
When type=add-reviewer-from-group-members, count defaults to 1
When type=add-reviewer-from-outside-collaborator-members, count defaults to 1
When type=add-assignee, the default value of count is the number of reviewers, meaning all will be added.

If the current number of reviewers or assignees is less than count, the list will be supplemented to reach the specified count.

If the current number of reviewers or assignees is greater than or equal to count, no action will be taken.

exclude

type: Array<String> | String
required: false

Exclude specified users.

reviewersConfig

type: IReviewersConfig | String
required: false

For the configuration of file reviewers or assignees, if the reviewers or assignees for the currently changed file are specified in the configuration, they will be added as reviewers or assignees.

Effective when type is add-reviewer or add-assignee.

Supports two formats:

String format, pass the configuration file relative path (supports json files):

reviewersConfig: config.json

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

Object format, pass the file reviewer configuration:

reviewersConfig:
  ./src: name1,name2
  .cnb.yml: name3

Among them, the key configured by the file reviewer or assginee is the relative path of the file; the value is the English name of the reviewer or assginee, separated by English commas.

If both reviewers and reviewersConfig are configured, a specified number of reviewers or assginees will be randomly selected from both.

role

type: ROLE_TYPE
required: false

The roles that reviewers or assginee can add include: Developer, Master, Owner. If Developer is selected, members with Developer and above permissions can be added, including Developer, Master, Owner.

Type Definitions

REVIEW_OPERATION_TYPE

Enum<String>

IReviewersConfig

{
    [key: String]: String
}

ROLE_TYPE

Enum<String>

Developer | Master | Owner

Output

Output result of adding reviewers：

{
  // Currently active reviewers
  "reviewers": [],

  // The at message format corresponding to reviewers is convenient for sending notifications
  "reviewersForAt": []
}

Output result of adding assignees：

{
  // Currently active assignees
  "assignees": [],

  // The at message format corresponding to assignees is convenient for sending notifications
  "assigneesForAt": []
}

Configuration Examples

Adding reviewers or assignees

.cnb.yml
main:
  pull_request:
    - stages:
        - name: Adding reviewers
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: aaa;bbb

        - name: Adding assignees
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc;ddd

Delete reviewers or assignees

.cnb.yml
main:
  pull_request:
    - stages:
        - name: Delete reviewers
          type: git:reviewer
          options:
            type: remove-reviewer
            reviewers: aaa

        - name: Delete assignees
          type: git:reviewer
          options:
            type: remove-assignee
            reviewers: aaa;bbb

Combine ifModify, add reviewer when certain files are modified

.cnb.yml
main:
  pull_request:
    - stages:
        - name: Modify config? Need special review
          ifModify:
            - ".cnb.yml"
            - "configs/**"
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: bbb

        - name: Modify config? Need special assignee
          ifModify:
            - ".cnb.yml"
            - "configs/**"
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc

Combine if, add certain people as reviewers or assignees under specified conditions

.cnb.yml
main:
  pull_request:
    - stages:
        - name: Release after work hours? Need specified person to review.
          if: |
            [ $(date +%H) -ge 18 ]
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: bbb

        - name: Release after work hours? Need specified person to assign.
          if: |
            [ $(date +%H) -ge 18 ]
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc

Randomly select a responsible person to review the code

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

Select a reviewer from the current repository members for review

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

Best Practices

Establish a dedicated CR group for cross-review and automatic merging

Randomly select N reviewers for the PR and notify them to the group.
Automatically merge after review passes.
Record reviewer information in the commit message.
Set up Git to meet the multi-reviewer automatic merging strategy to achieve cross-review.

.cnb.yml
main:
  review:
    - stages:
        - name: Auto merge after CR approval
          type: git:auto-merge
          options:
            mergeType: squash
            removeSourceBranch: true
            mergeCommitMessage: $CNB_LATEST_COMMIT_MESSAGE
          exports:
            reviewedBy: REVIEWED_BY
        # Send review messages to the WeCom robot
        - name: notify
          image: tencentcom/wecom-message
          settings:
            msgType: markdown
            robot: "155af237-6041-4125-9340-000000000000"
            content: |
              > Auto merge after CR approval <@${CNB_BUILD_USER}> 
              > 　
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              > 
              > ${REVIEWED_BY}

  pull_request:
    - stages:
        # ...Omit other tasks

        # Send to the CR dedicated group
        - 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

Repository Release

Applicable Events

push
branch.create
tag_push
pull_request.merged
api_trigger
web_trigger
tag_deploy

Parameters

overlying

type: Boolean
required: false
default: false

Overlay mode

true: Overlay mode, the same release can be submitted multiple times, and the final release is the union of multiple submissions. If an attachment with the same name already exists, it will be deleted and uploaded again to achieve the effect of updating.
false: Non-overlay mode, the last submission is taken as the standard, and previous ones are cleared.

Warning

By default, when the release version already exists, it will be deleted first and then regenerated.

title

type: String
required: false
default: tag name

The title of the release.

description

type: String
required: false

The description of the release.

preRelease

type: Boolean
required: false
default: false

Whether to set the release as a pre-release.

latest

type: String
required: false
default: false

Whether to set the release as the latest version.

Output

None

Configuration Examples

Generate changelog and automatically update the release description

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

Publish release when main branch is pushed

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

testing

coverage

testing:coverage

Unit Test Coverage, calculates the unit test coverage result through the unit test result report, and reports the badge.

Applicable Events

All Events

Full Coverage

Parsed from the local coverage report file, currently supports the following report formats:

json(js) (recommended)
json-summary
lcov (recommended)
jacoco
golang

Incremental Coverage

Coverage of the changed lines, only supports pull_request, pull_request.update, pull_request.target events.

Parameters

pattern

type: String
required: false

Glob format, specifies the location of the coverage report file, relative to the current working directory. If not specified, it will attempt to find the following files in the current directory (including subdirectories): coverage.json, jacoco*.xml, lcov.info, *.lcov.

lines

type: Number
required: false

Specifies the red line for full coverage, and if the full coverage percentage is less than this value, the workflow will be blocked and the pipeline will exit.

diffLines

type: Number
required: false

Specifies the red line for incremental coverage, and if the incremental coverage percentage is less than this value, the workflow will be blocked and the pipeline will exit. Incremental coverage results can be calculated for pull_request, pull_request.update, pull_request.target events, while other events only calculate full coverage.

allowExts

type: String
required: false

Whitelist of code file types participating in coverage calculation, separated by commas, e.g., .json,.ts,.js. If not specified, all files in the report will participate in the calculation.

lang

type: String
required: false

When the coverage result report target format is golang, please specify this parameter as go, otherwise there will be calculation errors. This parameter can be ignored in other cases.

breakIfNoCoverage

type: Boolean
required: false

Whether to throw an error and terminate the process when no coverage report file is found.

Output

{
    // Code line coverage, e.g., 100, value is NA if calculation fails
    lines,
    // Code incremental line coverage, e.g., 100, value is NA if calculation fails
    diff_pct,
}

Configuration Examples

.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
branch.create

Parameters

name

type: String
required: true

Artifact package name

type

type: String
required: false
default: docker

Artifact type, currently only supports docker and helm

Configuration Examples

.cnb.yml
main:
  push:
    - stages:
        - name: remove tag
          type: artifact:remove-tag
          options:
            # Package name
            # Package name example 1, repository same-name artifact: reponame
            # Package name example 2, repository non-same-name artifact: reponame/name
            name: reponame/name
            tags:
              - tag1
              - tag2
            type: docker