Built-in Plugin

About 9833 wordsAbout 33 min

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

Overview

docker:
- cache: Build Docker image cache to speed up dependency installation
cnb:
- await-resolve: Wait/notify mechanism for collaboration across multiple pipelines
- apply: Trigger sub-pipelines within the same repository
- trigger: Trigger sub-pipelines in a specified repository
- read-file: Export file content as environment variables
- destroy-token: Destroy the pipeline CNB_TOKEN.
vscode:
- go: Control the availability of remote development environments
git:
- reviewer: Automatically add reviewers to pull requests
- auto-merge: Automatically merge pull requests
- issue-update: Update issue status
- release: Release repository
- pr-commit-message-preset: Set pre-defined commit message for PR
- pr-update: Updating the title and labels of the pull request.
testing:
- coverage: Report unit test coverage
artifact:
- remove-tag: Remove CNB artifact tags
tapd:
- status-update: Update the status of TAPD-associated items (story, task, or bug).
- comment: Submit TAPD associated item (story, task, or bug) comments.

Docker

cache

docker:cache

Docker Cache, builds a Docker image as a cache to be reused in future builds.

It helps avoid redundant downloads of network resources such as dependencies.

Parameters

dockerfile

type: String
required: true

The path to the Dockerfile used to build the cache image.

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

by

type: Array<String> | String
required: false

Specifies the list of files that the cache image build process depends on.

Note: Files not listed in by, except for the Dockerfile, are treated as non-existent during the image build process.

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, it defaults to the value of by.

When the content of the file pointed to by versionBy changes, a new version is considered. The calculation logic is based on the expression:

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 arguments during build (--build-arg $key=$value). If the value is null, only the key is added (--build-arg $key).

target

type: String
required: false

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

sync

type: Boolean
required: false
default: false

Specifies whether to operate in synchronous mode. If true, it waits for the cache image to be successfully pushed before proceeding with subsequent tasks.

ignoreBuildArgsInVersion

type: Boolean
required: false
default: false

Specifies whether to ignore buildArgs in version calculation.

See Version Control

Output Results

{
  // The docker image name corresponding to the 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, string
            by:
              - package.json
              - package-lock.json
            versionBy:
              - package-lock.json
          exports:
            name: DOCKER_CACHE_IMAGE_NAME
        - name: use cache
          image: $DOCKER_CACHE_IMAGE_NAME
          commands:
            - cp -r "$NODE_PATH" ./node_modules
        - name: build with cache
          script:
            - npm run build

Where cache.dockerfile is a Dockerfile used to build the cache image, for example:

# Choose a Base image
FROM node:14

# Set working directory
WORKDIR /space

# Copy the file list from 'by'
COPY . .

# Install dependencies based on the copied files
RUN npm ci

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

cnb

await-resolve

cnb:await
cnb:resolve

await waits for the execution of resolve, which can pass variables to await.

Through await-resolve, multiple concurrent pipelines can cooperate with each other, enabling more flexible sequence control.

Tips

Difference between await-resolve and apply, trigger:

The former refers to a pipeline in a build that waits at an await task until it receives a resolve notification from another pipeline corresponding to the key before continuing.

The latter triggers a new pipeline from an existing one. It can be asynchronous, synchronous, and can even span repositories.

Usage Limitations

Can only await and resolve pipelines triggered by the same event.
A key can only be resolved once but can be awaited multiple times.
Group await and resolve operations using a key.
Await-resolve tasks can only run in the 'stages' of the pipeline, not in the 'endStages' and 'failStages'.

Deadlock Detection

While await and resolve can provide flexible flow control, they can introduce complex edge cases such as:

Deadlocks
- Pipeline-1 and Pipeline-2 await each other
- Multiple pipelines form an await loop
Infinite waiting
- Awaiting a non-existent key or a key without a corresponding resolve
- Failure in the pipeline where resolve is executed
Duplicate resolves
- Multiple resolve tasks associated with the same key

The deadlock detection mechanism automatically detects these anomalies, terminates the await's waiting state, and throws a dead lock found. exception.

The order of await and resolve in the configuration file does not affect the execution result. The final await task will always wait for the corresponding resolve to complete, and this scenario will not be terminated by the 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 be passed

In key: value format, supports multiple levels. Example:

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

The result of the await task is the data object declared by resolve. This object can be accessed 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

Alternatively, you can simply indicate a waiting action without passing any content:

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

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

Output Results

{
  // Content returned by resolve
  data
}

apply

cnb:apply

Triggers a custom event pipeline in the current repository.

Applicable Events

push
commit.add
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

Specifies a local file as the configuration file.

event

type: String
required: false
default: api_trigger

Name of the custom event to execute, must be api_trigger or start with api_trigger_.

sync

type: Boolean
required: false
default: false

Whether to execute synchronously.

In synchronous mode, it waits for the current apply pipeline to succeed before executing the next task.

continueOnBuildError

type: Boolean
required: false
default: false

In synchronous mode, whether to continue executing the next task when the triggered pipeline build fails.

title

type: String
required: false

Custom pipeline title.

Environment Variables Related

Pass business-defined environment variables visible to the current job in the new pipeline.

Default values include the following environment variables that cannot be overridden by users:

APPLY_TRIGGER_BUILD_ID (similar to CNB_BUILD_ID in default CI environment variables)
APPLY_TRIGGER_PIPELINE_ID (similar to CNB_PIPELINE_ID in default CI environment variables)
APPLY_TRIGGER_REPO_SLUG (similar to CNB_REPO_SLUG in default CI environment variables)
APPLY_TRIGGER_REPO_ID (similar to CNB_REPO_ID in default CI environment variables)
APPLY_TRIGGER_USER (similar to CNB_BUILD_USER in default CI environment variables)
APPLY_TRIGGER_BRANCH (similar to CNB_BRANCH in default CI environment variables)
APPLY_TRIGGER_COMMIT (similar to CNB_COMMIT in default CI environment variables)
APPLY_TRIGGER_COMMIT_SHORT (similar to CNB_COMMIT_SHORT in default CI environment variables)
APPLY_TRIGGER_ORIGIN_EVENT (similar to CNB_EVENT in default CI environment variables)
CNB_PULL_REQUEST_ID (similar to CNB_PULL_REQUEST_ID in default CI environment variables)
CNB_PULL_REQUEST_IID (similar to CNB_PULL_REQUEST_IID in default CI environment variables)
CNB_PULL_REQUEST_MERGE_SHA (similar to CNB_PULL_REQUEST_MERGE_SHA in default CI environment variables)

Config Value Priority

Values are retrieved in the following order until a value is found:

config
configFrom
.cnb.yml in the current repository
If apply is called in the pull_request.merged event, the merged configuration file is used
If apply is called in the pull_request.target or pull_request.mergeable events, the configuration file of the target branch is used
Otherwise, the configuration file of the current branch is used

The configFrom parameter only supports local files like ./test/.cnb.yml. If you need to use a remote file, you should download it locally first.

Output Results

{
  "sn": "cnb-i5o-1ht8e12hi", // Build number
  "buildLogUrl": "https://cnb.cool/<your-repo-slug>/-/build/logs/cnb-i5o-1ht8e12hi", // Build log link
  "message": "success",
  "buildSuccess": true, // Whether the triggered build was successful, this key only exists in synchronous mode
  "lastJobExports": {} // Environment variables exported by the last job in 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 in 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

Trigger

cnb:trigger

Triggers a custom event pipeline in a specified repository within the current repository (requires permission to trigger the corresponding repository pipeline).

Applicable Events
Parameters
Output Results
Configuration Examples
- Basic Usage

Applicable Events

All Events

token

type: String
default: Environment variable CNB_TOKEN

Personal access token.

The new pipeline triggerer is the user corresponding to the token, and it will check for permissions to trigger the target repository pipeline.

slug

type: String
required: true

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

event

type: String
required: true

Name of the custom event to trigger, must be api_trigger or start with api_trigger_.

The target repository must have a pipeline configured for the corresponding branch and event to be triggered.

branch

type: String
required: false

Branch to trigger, defaults to the main branch of the target repository.

sha

type: String
required: false

CommitId in the triggering branch, defaults to the latest commit record of the branch.

env

type: TriggerEnv
required: false

Environment variables to pass when triggering the target repository pipeline.

Default values include the following environment variables that cannot be overridden by users:

API_TRIGGER_BUILD_ID (similar to CNB_BUILD_ID in default CI environment variables)
API_TRIGGER_PIPELINE_ID (similar to CNB_PIPELINE_ID in default CI environment variables)
API_TRIGGER_REPO_SLUG (similar to CNB_REPO_SLUG in default CI environment variables)
API_TRIGGER_REPO_ID (similar to CNB_REPO_ID in default CI environment variables)
API_TRIGGER_USER (similar to CNB_BUILD_USER in default CI environment variables)
API_TRIGGER_BRANCH (similar to CNB_BRANCH in default CI environment variables)
API_TRIGGER_COMMIT (similar to CNB_COMMIT in default CI environment variables)
API_TRIGGER_COMMIT_SHORT (similar to CNB_COMMIT_SHORT in default CI environment variables)

sync

type: Boolean
required: false
default: false

Whether to execute synchronously. In synchronous mode, it waits for the current trigger pipeline to succeed before executing the next task.

continueOnBuildError

type: Boolean
required: false
default: false

In synchronous mode, whether to continue executing the next task if the triggered pipeline build fails.

title

type: String
required: false

Custom pipeline title.

Type Definitions

TriggerEnv

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

Output Results

{
  "sn": "cnb-i5o-1ht8e12hi", // Build number
  "buildLogUrl": "https://cnb.cool/<your-repo-slug>/-/build/logs/cnb-i5o-1ht8e12hi", // Build log link
  "message": "success",
  "buildSuccess": true, // Whether the triggered build was successful, this key only exists in synchronous mode
  "lastJobExports": {} // Environment variables exported by the last job in the triggered pipeline
}

Configuration Examples

Basic Usage

Trigger a pipeline in the main branch of a specified repository in the current repository.

The pipeline configuration file uses the .cnb.yml file from the main branch of the repository.

Use the access token $TOKEN to check if the user has permission to trigger the target repository pipeline.

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

Reads the content of a specified file, which can be exported as an environment variable for use in subsequent tasks.

Using the ##[set-output key=value] command to output variables is more convenient but will display the content in the logs, making it unsuitable for sensitive information.

For sensitive information that is predetermined, you can use imports for importing, and for sensitive information generated during the build process, you can write it to a file and use this built-in task to read it.

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

The file type is determined by the suffix, currently supporting .json, .yml, .yaml, and plain text (key=value structure).

Applicable Events
Parameters
Output Results
Configuration Examples

Applicable Events

All Events

Parameters

filePath

type: String
required: true

Local file path.

Output Results

{
  // Object read from the file
}

Configuration Examples

Write some variables needed for subsequent tasks to a file, then use this built-in task to read the file and export it as environment variables for use in 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 a multi-level key
            $myKey.myVar: ENV_ENV_KEY_MY_VAR # Get the key specified through an environment variable
        - name: echo env
          script:
            - echo $ENV_MY_VAR
            - echo $ENV_DEEP_MY_VAR
            - echo $ENV_ENV_KEY_MY_VAR

destroy-token

cnb:destroy-token

A CNB_TOKEN is created before the pipeline starts and is destroyed after it ends. Use this task to proactively destroy the CNB_TOKEN and remove this environment variable.

Applicable Events

All Events

Parameters

None

Output

None

Configuration Examples

Proactively destroy the CNB_TOKEN after use in the pipeline to reduce the risk of CNB_TOKEN misuse.

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

Difference in configuring this built-in task for remote development:

Using this task: When starting cloud-native development, you need to wait for this task to complete before the WebIDE and VSCode/Cursor client entry points appear.
Not using this task: After the pipeline's prepare stage completes (code-server code service starts), the WebIDE and VSCode/Cursor client entry points will appear before the stages tasks are executed.

The difference in the timing of the appearance of the entry points mentioned above refers to the transition from the loading waiting page to the entry point selection page. In reality, whether or not this task is used, remote development is already available once the code-server code service has started.

Note: Using this task will increase the waiting time. If you need to delay developers' entry into the environment until certain tasks are completed, you can use this task.

Applicable Events
Output Results
Configuration Examples

Applicable Events

vscode
branch.create
api_trigger
web_trigger

Output Results

{
  // WebIDE URL
  "url": ""
}

Configuration Examples

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

git

auto-merge

git:auto-merge

Automatically merges a Pull Request, typically used after the pull_request pipeline checks and code review, in the pull_request.mergeable pipeline to automatically merge the PR without manual intervention.

The triggering conditions and timing of the pull_request.mergeable event can be found in the events.

Applicable Events
Parameters
Output Results
Configuration Examples
- Stand-alone Usage
- Used with Target Branch Push Event
Best Practices

Applicable Events

pull_request.mergeable

Parameters

mergeType
mergeCommitMessage
mergeCommitFooter
removeSourceBranch
ignoreAssignee

mergeType

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

Merge strategy, defaulting to auto: merges by merge if multiple people contribute, otherwise uses squash.

mergeCommitMessage

type: String
required: false

Commit message for the merge.

When the merge strategy is rebase, this information is not required.
When the merge strategy is merge, the default message is chore: merge node(merged by CNB), automatically appending PR references, reviewers' names, and contributors' names. For example:

chore: merge node(merged by CNB)

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

When the merge strategy is squash, the default value is the first commit message of the PR. It also appends PR references, reviewers' names, and contributors' names. For example:

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

This configuration will result in the following effect:

Suppose a PR (feat/model-a -> main) has two commit records:

Commit 1: Submitted on October 1, 2023

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

Due to some reason, add a certain feature

close #10

Commit 2: Fixed some issues pointed out during code review, submitted on October 2, 2023

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

After automatic merging, a commit node like this will appear on the main branch, where the subsequent commit record (Commit 2) will be erased:

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

Due to some reason, add a certain feature

close #10

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

Here’s the translation of your Chinese text into English:

It can also be directly specified

For example, specifying it as the title of the current PR through an environment variable:

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

mergeCommitFooter

type: String
required: false

Footer information to be set for the merge, with multiple footers separated by \n, effective only for merge and squash.

When the merge strategy is rebase, this information is not required.

When the merge strategy is merge or squash, the provided information will be added as footers line by line, followed by PR references, reviewers' names, and contributors' names. For 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 the source branch after merging.

This value is irrelevant when the source branch and target branch are in different repositories.

ignoreAssignee

type: Boolean
required: false
default: false

Whether to ignore the assignee.

When a PR has a specified assignee, this task will not automatically merge the PR because the assignee is meant to assign someone to handle it manually.

Setting this to true allows for forcibly merging the PR even if there is an assignee.

Output Results

{
    reviewedBy, // String, information of the contributor appended to the commit message
    reviewers, // Array<String>, list of reviewers
}

Configuration Examples

Stand-alone Usage

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

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

Used with Target Branch `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 the main branch triggers the pull_request.mergeable event, the PR will be automatically merged using the merge method.

After the merge, the last reviewer who approved the review will act as the trigger, initiating the push event on the target branch (main), and the declared build and publish processes will continue to execute.

Best Practices

Using `squash` Auto-Merge

Utilize squash merging to create only one commit node on the target branch for each PR and optionally delete the source branch if permissions allow.

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

Automatically Selecting Merge Type with `auto`

Automatically determine the merge type based on whether multiple people are contributing (use merge) or if it's a single contributor (use squash).

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

Establishing a Dedicated CR Group for Cross-Review Auto-Merge

Automatically merge after code review approval.
Include reviewer information in the commit message.

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

  pull_request:
    - stages:
        # ...other tasks omitted
        - 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 an issue, and modify issue labels.

Applicable Events
Work Mechanism
How to Get Issue
Including Issue in Commit Logs
Parameters
Output Results
Permission Check
Configuration Examples

Applicable Events

All Events

Work Mechanism

Check if the issue exists -> Check if it meets the when condition (optional) -> Check if it meets the lint condition (optional) -> Update issue status or labels

Issue Retrieval Method

1. When fromFile or fromText parameters are provided:

Retrieve and parse from the provided text file or text. fromFile takes precedence over fromText.

2. When neither fromFile nor fromText parameters are provided:

PR-related events:
Retrieve and parse from the commit logs of the PR's commits.
commit.add event:
Retrieve and parse from the commit logs of the newly added commits.
push event for non-new branches:
Retrieve and parse from the commit logs of the pushed commits.
Other cases:
Retrieve and parse from the commit log of the latest commit.

Tips

If you need to use this in a branch.delete event, since the branch has already been deleted and cannot be retrieved from the context, you must provide the parsing content using the fromText or fromFile parameter.

Retrieval Method: Extract the following two formats from the above text:

#IssueID: Represents an Issue in the current repository. For example, #123 refers to Issue ID 123 in the current repository.
groupName/repoName#IssueID: Represents a cross-repository (other repository) Issue. For example, test/test#123 refers to Issue ID 123 in the test/test repository.

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

Including Issue in Commit Logs

When committing code, you can include the associated IssueID in the commit log, which can be automatically extracted when using the current built-in task to update the associated issue for updating labels and status.

It is recommended to include the IssueID in the body of the commit log. Here are two command-line methods:

Method 1: Use shift + enter for a new line, and it's recommended to add a blank line between the title and body.

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

cnb/feedback#123"

Method 2: Using this method will create two new lines between the title and body.

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

Parameters

fromText
fromFile
state
label
when
lint
defaultColor
prefix

fromText

Type: String
Required: false

Parses IssueId from the provided text.

If not specified, it automatically parses from the commit records in the context. You can specify a text containing IssueId references to declare the target, such as when used in conjunction with a changelog generation plugin to automatically extract IssueId from the changelog.

fromFile

type: String
required: false

Reads content from a text file and parses IssueId. This takes precedence over fromText.

When the content is too large, it is recommended to use this parameter to pass the content via a file to avoid exceeding limits.

state

type: IssueStateMap
required: false

Corresponds to the state attribute. When set to close, it can close the Issue.

label

type: UpdateLabel
required: false

Description of the operation on labels.

when

type: IssueUpdateStatus
required: false

Filter conditions, where multiple conditions are connected by or. When empty, it indicates operations on all Issues.

lint

type: IssueUpdateStatus
required: false

Check if the Issue meets the conditions. If not met, an exception is thrown. Multiple conditions are connected by or, and when empty, no checks are performed.

defaultColor

type: String
required: false

Default color for added labels, effective only when the label.add parameter is provided.

prefix

type: String[]
required: false

The issue prefixes that need to be processed, for example, if close and closed is passed, it will handle all issues prefixed with close and closed. For instance, close #123 or closed #123 #456.

Type Definitions

IssueStateMap

Enum<String>: open | close

UpdateLabel

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, where multiple values are connected by or.

Output Results

{
    issues // List of issues
}

Permission Check

If the issue that needs to be updated belongs to the repository to which the pipeline belongs, and the event is not pull_request, pull_request.update, pull_request.approved, or pull_request.changes_requested, then the permission of the pipeline triggerer to modify the issue will not be checked.

Configuration Examples

After merging into main, update labels

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

When a tag is pushed, close the issue and update labels

.cnb.yml
$:
  tag_push:
    - stages:
        - name: release operation
          script: echo "Use release tasks instead of the current task"
        # Perform issue update operation after release operation
        - name: update issue
          type: git:issue-update
          options:
            # Close the issue
            state: close
            # You can specify prefixes for issues that need to be closed. If set, only those containing "close #123" or "closed #123" will be closed.
            # prefix:
            #   - close
            #   - closed
            # Remove the "Pre-release" label and add the "Released" label
            label:
              add: Released
              remove: Pre-release
            # Perform the above operations only when there are "feature" or "bug" labels
            when:
              label:
                - feature
                - bug

When tag is pushed, find IssueId included in the changes between the current tag and the previous tag, and add labels

.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: Requirement Accepted
            when:
              label: feature

Reviewer

git:reviewer

Configure reviewers or assignees to add or remove reviewers/assignees to a PR, with the option to specify a range of alternative reviewers/assignees.

Applicable Events
Parameters
Output Results
Configuration Examples
Best Practices

Applicable Events

pull_request
pull_request.target
pull_request.update

Under pull_request and pull_request.update events, the trigger will check if the initiator has permission to operate on reviewers/assignees. This check is not performed under the pull_request.target event. For PRs submitted across repositories, there may be cases where the initiator lacks permission. In such cases, it is recommended to use the pull_request.target event.

Parameters

type
reviewers
count
exclude
reviewersConfig
role
skip_on_wip

type

type: REVIEW_OPERATION_TYPE
required: false
default: add-reviewer

Operation type:

add-reviewer: Add reviewers, selecting a specified number of reviewers from the reviewers parameter
add-reviewer-from-repo-members: Select one reviewer directly from repository members and add them as a reviewer
add-reviewer-from-group-members: Select one reviewer from the repository's parent organization (direct superior organization) and add them as a reviewer
add-reviewer-from-outside-collaborator-members: Select one reviewer from the repository's external collaborators and add them as a reviewer
remove-reviewer: Remove specified members from existing reviewers
add-assignee: Add assignees, adding members specified in the reviewers parameter
remove-assignee: Remove specified members from existing assignees

reviewers

type: Array<String> | String
required: false

Usernames of reviewers to add or remove. Multiple usernames can be separated by , or ;.

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

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

count

type: Number
required: false

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

When type is add-reviewer or add-assignee, the default value for count is the number of reviewers, meaning all are added.
When type is add-reviewer-from-repo-members, add-reviewer-from-group-members, or add-reviewer-from-outside-collaborator-members:
- If the target branch is a protected branch with a requirement for reviewer approvals, the default value for count is the number of reviewers required for approval.
- In other cases, the default value for count is 1.

If the number of existing reviewers or assignees is < count, then fill up to the specified count.

If the number of existing reviewers or assignees is >= count, then no action is taken.

exclude

type: Array<String> | String
required: false

Exclude specified users.

reviewersConfig

type: IReviewersConfig | String
required: false

File reviewers or assignees configuration. If the configuration includes reviewers or assignees for the current changed file, they will be added as reviewers or assignees.

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

Supports two formats:

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

{
  "reviewersConfig": "config.json"
}

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

Object format, passing the file reviewers configuration:

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

In the file reviewers or assignees configuration, the key is the relative file path, and the value is the usernames of reviewers or assignees separated by commas.

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

role

type: ROLE_TYPE
required: false

Roles that reviewers or assignees can have include: Developer, Master, Owner. If Developer is selected, members with Developer and higher permissions can be added, including Developer, Master, Owner.

skip_on_wip

type: Boolean
required: false
default: true

Whether to skip the operation when the pull request is a WIP pull request. The default value is true.

true: the operation will be skipped when the pull request is a WIP pull request.
false: the operation will be performed regardless of whether the pull request is a WIP pull request.

Type Definitions

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

Output Results

Output result for adding reviewers:

{
  "reviewers": [],
  "reviewersForAt": []
}

Output result for adding assignees:

{
  "assignees": [],
  "assigneesForAt": []
}

Configuration Examples

Adding reviewers and assignees:

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

        - name: Add Assignees
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc;ddd

Delete reviewers or assignees:

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

        - name: Remove Assignees
          type: git:reviewer
          options:
            type: remove-assignee
            reviewers: aaa

Combining with ifModify, adding reviewers and assignees when specific files are modified:

.cnb.yml
main:
  pull_request:
    - stages:
        - name: Review for Configuration Changes
          ifModify:
            - ".cnb.yml"
            - "configs/**"
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: bbb

        - name: Assign for Configuration Changes
          ifModify:
            - ".cnb.yml"
            - "configs/**"
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc

Combining with if, adding specific reviewers or assignees under certain conditions:

.cnb.yml
main:
  pull_request:
    - stages:
        - name: Release after Hours? Requires Reviewers.
          if: |
            [ $(date +%H) -ge 18 ]
          type: git:reviewer
          options:
            type: add-reviewer
            reviewers: bbb

        - name: Release after Hours? Requires Assignees.
          if: |
            [ $(date +%H) -ge 18 ]
          type: git:reviewer
          options:
            type: add-assignee
            reviewers: ccc

Randomly selecting one person to review the code:

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

Selecting one reviewer from 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 code review (CR) group for cross-review and automatic merging.

Randomly select N reviewers for a PR and notify the group.
Automatically merge after the review is approved.
Record reviewer information in the commit message.
Configure Git to automatically merge based on multi-reviewer approval policies for 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 message to WeChat Enterprise Bot
        - 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:
        # ...Other tasks omitted

        # Send to dedicated CR group
        - name: Add Reviewers
          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"
            content: |
              > ${CURR_REVIEWER_FOR_AT}
              >  
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              >  
              > from ${CNB_BUILD_USER}

Release

git:release

Publish a Release for the repository

Applicable Events
Parameters
Output Results
Configuration Examples

Applicable Events

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

Parameters

overlying
tag
title
description
descriptionFromFile
preRelease
latest

Tips

This built-in task does not support uploading attachments. You can use the cnbcool/attachments task to upload attachments.

overlying

type: Boolean
required: false
default: false

Overlay mode:

true: Overlay mode, meaning this is only for editing or updating the Release.
false: Non-overlay mode, meaning delete first, then recreate the Release.

Warning

Default is false, meaning that when a Release version already exists, it will be deleted first and then recreated.

title

type: String
required: false
default: Tag name

Title of the Release.

description

type: String
required: false

Description of the Release. When the content is too large, it is recommended to use the descriptionFromFile parameter to pass the content through a file to avoid exceeding limits.

Warning

description and descriptionFromFile are mutually exclusive and cannot be specified at the same time.

descriptionFromFile

type: String
required: false

Read content from a file and use it as the description of the Release.

Specify a local file path, and the system will read the file content and use it as the description of the Release.

Warning

description and descriptionFromFile are mutually exclusive and cannot be specified at the same time.

preRelease

type: Boolean
required: false
default: false

Whether to set the release as a pre-release.

latest

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

Whether to set the Release as the latest version.

Output Results

None

Configuration Examples

Generate changelog and automatically update Release description:

.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

Publish a Release when pushing to the main branch:

.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

Set pre-defined commit message for PR.

When users select Merge or Squash merge in the PR interface, this message will be automatically inserted into the commit message.

Applicable Events

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

Parameters

message

message

type: String
required: true

Pre-set commit message for the PR.

Output Results

None

Configuration Example

.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

Updating PR Labels and Title

Applicable Events

All Events

How to Get PR ID

1. When fromFile or fromText parameters are provided:

Parse the PR from the provided text file or text. fromFile takes precedence over fromText.

2. When fromFile or fromText parameters are not provided:

PR-related events:
Parse from the commit logs of the PR's commits. Additionally, include the current PR.
commit.add event:
Parse from the commit logs of the newly added commits.
Non-new branch push event:
Parse from the commit logs of the current push.
Other cases:
Parse from the commit log of the latest commit.

Tips

If you need to use this in a branch.delete event, since the branch has been deleted and cannot be retrieved from the context, you must provide the content to parse using the fromText or fromFile parameters.

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

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

Where:

your-repo-slug is the repository path, e.g., cnbcool/cnb.
number is the PR number, found after the PR page URL.

To distinguish from an Issue, the prefix PR-URL: is required.

Note: Ensure there is a space before #123 or test/test#123.

Parameters

fromText

type: String
required: false

Parse the PR from the provided text.

If not declared, it will automatically parse from the commit logs in the context. You can specify a text containing a PR ID reference to declare the target, such as using it with a changelog generation plugin to automatically extract the PR ID from the changelog.

fromFile

type: String
required: false

Read and parse the PR from a text file. Takes precedence over fromText.

label

type: UpdateLabel
required: false

Labels to be added or removed.

title

type: String
required: false

The title of the PR.

defaultColor

type: String
required: false

The default color for the added label. This is only applicable when the label.add parameter is provided.

Output Results

{
    pullRequests // List of modified PRs
}

Permission Check

If the PRs to be updated belong to the pipeline's repository, and the events are not pull_request, pull_request.update, pull_request.approved, or pull_request.changes_requested, the pipeline triggerer's permissions to modify the PR will not be checked.

Configuration Examples

The following pipeline implements the following functionalities:

When the pull_request pipeline fails: Add the label To be modified.
When the pull_request pipeline succeeds: Add the label Pending review and remove the label To be modified.
When the pull_request.merged pipeline runs: Add the label To be released and remove the label Pending review.

.cnb.yml
main:
  pull_request:
    - stages:
        - name: check
          script: echo "do some check"
        - name: Add PR label - Pending review
          type: git:pr-update
          options:
            label:
              add:
                - Pending-review
              remove:
                - To-be-modified
      failStages:
        - name: Add PR label - To be modified
          type: git:pr-update
          options:
            label:
              add:
                - To-be-modified

  pull_request.merged:
    - stages:
        - name: check
          script: echo "do some check"
        - name: Add PR label - To be released
          type: git:pr-update
          options:
            label:
              add:
                - To-be-released
              remove:
                - Pending-review

Testing

Coverage

testing:coverage

Unit Test Coverage, calculates the coverage based on unit test result reports and reports badge data.

You can view the coverage badge data of the latest 100 commits by branch in the repository's Insights page in the form of charts.

Tips

For coverage data uploaded by pipelines triggered by events related to Pull Requests (except pull_request.merged), switch to the pull request view to see the unit test insights curve.

Applicable Events
Full Coverage
Incremental Coverage
Parameters
Output Results
Configuration Examples

Applicable Events

push
commit.add
pull_request

Full Coverage

Parsed from local coverage report files, currently recognizing the following report formats:

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

Incremental Coverage

Parameters

key
name
pattern
lines
diffLines
allowExts
lang
breakIfNoCoverage

key

type: String
required: false

Coverage data key values, used to distinguish between different types of coverage data, such as frontend, backend, etc.

name

type: String
required: false

Coverage data names, used for display in badges, correspond one-to-one with coverage data keys. When a key does not exist, the name will be ignored.

For example: key: frontend, name: frontend coverage

pattern

type: String
required: false

In Glob format, specifies the location of the coverage report file relative to the current working directory. If not provided, it will try 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 full coverage red line. If the full coverage percentage is less than this value, the workflow will be blocked from exiting the pipeline.

diffLines

type: Number
required: false

Specifies the incremental coverage red line. If the full coverage percentage is less than this value, the workflow will be blocked from exiting the pipeline. Events like pull_request, pull_request.update, pull_request.target support calculating incremental coverage results, while other events only calculate full coverage.

allowExts

type: String
required: false

Whitelist of code file types to be included in coverage calculation, separated by commas, e.g., .json, .ts, .js. If not provided, all files in the report will be included in the calculation.

lang

type: String
required: false

When the coverage report target format is golang, specify this parameter as go to avoid calculation errors. This parameter can be ignored in other cases.

breakIfNoCoverage

type: Boolean
required: false

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

Output Results

{
  // Code line coverage, e.g., 100. Value is NA if calculation fails.
  "lines": 100,
  // Incremental code line coverage, e.g., 100. Value is NA if calculation fails.
  "diff_pct": 100
}

Configuration Examples

.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

Delete CNB Artifact Tags, currently only supports deleting CNB Docker and Helm tags. Write permissions for the repository are required.

Applicable Events
Parameters
Configuration Examples

Applicable Events

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

Parameters

name
tags
type

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 with the same name artifact: reponame
            # Package name example 2, repository with a different name artifact: reponame/name
            name: reponame/name
            tags:
              - tag1
              - tag2
            type: docker

TAPD

When submitting code, you can add TAPD source code keywords in the commit message or PR description. The cloud-native build system will automatically recognize and associate commits, PRs, and TAPD work items.

In pipelines triggered by code pushes, PRs, and tags, you can update the information of TAPD-associated items through the following tasks.

Prerequisites

The TAPD feature must be enabled in the root organization.
The pipeline triggerer must have a bound TAPD account.

TAPD Association Item Filtering Rules

The pipeline will filter associated TAPD work items based on the following rules:

1. When the fromFile or fromText parameters are provided:

Parse the commit IDs from the provided text file or text, and query the associated TAPD work items.

The fromFile parameter takes precedence over fromText.

2. When neither the fromFile nor fromText parameters are provided:

PR-related events:
Query the TAPD work items associated with the commits and PR description of the PR.
commit.add event:
Query the TAPD work items associated with the newly added commits.
push event for non-new branches:
Retrieve the associated TAPD work items from the commit logs of all commits in this push.
Other cases:
Query the TAPD work items associated with the latest commit.

Through the above rules, ensure systematic and efficient association between code changes and TAPD work items.

TAPD Association Item Types
The type in the TAPD work item source code keyword is the work item type, such as: story, task, bug.

Note: The source code keyword for TAPD tasks may be either story or task. Please distinguish carefully.

Type: String
Required: true
Target status.

when

Type: String | Array<String>
Required: false

Update work items with the specified status. No filtering is applied if left empty.

type

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

Update work items of the specified type. No filtering is applied if left empty.

fromText

Type: String
Required: false

Parse commit IDs (up to 50) from the provided text and query their associated work items.

Configuration Examples

Update the status of all TAPD-associated items:

.cnb.yml
main:
  push:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: developing

Update the status of TAPD-associated items that meet specific conditions:

.cnb.yml
main:
  pull_request.merged:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: Completed
            when:
              - developing
            type: story

Parse commit IDs from fromText, query TAPD-associated items, and update their status:

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

Type: String
Required: true

Comment content.

when

Type: String | Array<String>
Required: false

Comment on work items with the specified status. No filtering is applied if left empty.

type

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

Comment on work items of the specified type. No filtering is applied if left empty.

fromText

Type: String
Required: false

Parse commit IDs (up to 50) from the provided text and query their associated work items.

Configuration Examples

Comment on all TAPD-associated items:

.cnb.yml
main:
  push:
    - stages:
        - name: add tapd comment
          type: tapd:comment
          options:
            comment: Start development

Comment on TAPD-associated items that meet specific conditions:

.cnb.yml
main:
  pull_request.merged:
    - stages:
        - name: add tapd comment
          type: tapd:comment
          options:
            comment: Merged
            when:
              - developing
            type: story

Parse commit IDs from fromText, query TAPD-associated items, and comment on them:

.cnb.yml
$:
  tag_push:
    - stages:
        - name: Generate changelog
          image: cnbcool/changelog
          settings:
            dryRun: true
            linkReferences: false
          exports:
            latestChangeLog: RELEASE_NOTES
        - name: tapd
          type: tapd:comment
          options:
            comment: published
            type: story
            fromText: $RELEASE_NOTES