---
url: /en/build/internal-steps.md
---
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](#docker-cache): Build Docker image cache to speed up dependency installation
* cnb:
  * [await-resolve](#cnb-await-resolve): Wait/notify mechanism for collaboration across multiple pipelines
  * [apply](#cnb-apply): Trigger sub-pipelines within the same repository
  * [trigger](#cnb-trigger): Trigger sub-pipelines in a specified repository
  * [read-file](#cnb-read-file): Export file content as environment variables
  * [destroy-token](#cnb-destroy-token): Destroy the pipeline [CNB\_TOKEN](../build-in-env.md#cnb_token).
* vscode:
  * [go](#vscode-go): Control the availability of Workspaces environments
* git:
  * [reviewer](#git-reviewer): Automatically add reviewers to pull requests
  * [auto-merge](#git-auto-merge): Automatically merge pull requests
  * [issue-update](#git-issue-update): Update issue status
  * [release](#git-release): Release repository
  * [pr-commit-message-preset](#git-pr-commit-message-preset): Set pre-defined commit message for PR
  * [pr-update](#git-pr-update): Updating the title and labels of the pull request.
* testing:
  * [coverage](#testing-coverage): Report unit test coverage
* artifact:
  * [remove-tag](#artifact-remove-tag): Remove CNB artifact tags
* tapd:
  * [status-update](#tapd-status-update): Update the status of TAPD-associated items (story, task, or bug).
  * [comment](#tapd-comment): Submit TAPD associated item (story, task, or bug) comments.
* knowledge:
  * [update](#knowledge-update): Build repository documents, issues, etc., and upload them to the knowledge base.
* npc:
  * [go](#npc-go): Execute NPC tasks

## Docker

### cache {#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`.

* [Applicable Events](./#docker-cache-applicable-events)
* [Parameters](./#docker-cache-parameters)
* [Output Results](./#docker-cache-output)
* [Configuration Examples](./#docker-cache-configuration-examples)

#### Applicable Events {#docker-cache-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Parameters {#docker-cache-parameters}

* [dockerfile](./#docker-cache-parameters-dockerfile)
* [by](./#docker-cache-parameters-by)
* [versionBy](./#docker-cache-parameters-versionBy)
* [buildArgs](./#docker-cache-parameters-buildArgs)
* [target](./#docker-cache-parameters-target)
* [sync](./#docker-cache-parameters-sync)
* [ignoreBuildArgsInVersion](./#docker-cache-parameters-ignoreBuildArgsInVersion)

##### dockerfile {#docker-cache-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](../grammar.md#job-timeout) parameter.

##### by {#docker-cache-parameters-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 {#docker-cache-parameters-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 {#docker-cache-parameters-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 {#docker-cache-parameters-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 {#docker-cache-parameters-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 {#docker-cache-parameters-ignoreBuildArgsInVersion}

* type: `Boolean`
* required: `false`
* default: `false`

Specifies whether to ignore `buildArgs` in version calculation.

See [Version Control](#docker-cache-parameters-versionBy)

#### Output Results {#docker-cache-output}

```javascript
{
  // The docker image name corresponding to the cache
  name;
}
```

#### Configuration Examples {#docker-cache-configuration-examples}

```yaml title=".cnb.yml"
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:

```dockerfile
# 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 {#cnb-await}

See [await-resolve](./#cnb-await-resolve)

### resolve {#cnb-resolve}

See [await-resolve](./#cnb-await-resolve)

### await-resolve {#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.

:::tip

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](./#cnb-await-resolve-usage-limitations)
* [Deadlock Detection](./#cnb-await-resolve-deadlock-detection)
* [Applicable Events](./#cnb-await-resolve-applicable-events)
* [Await Parameters](./#cnb-await-resolve-await-parameters)
* [Resolve Parameters](./#cnb-await-resolve-resolve-parameters)
* [Output Results](./#cnb-await-resolve-output)

#### Usage Limitations {#cnb-await-resolve-usage-limitations}

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

#### Deadlock Detection {#cnb-await-resolve-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 {#cnb-await-resolve-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Await Parameters {#cnb-await-resolve-await-parameters}

##### key {#cnb-await-resolve-await-parameters-key}

* type: String
* required: true

Pairing ID

#### Resolve Parameters {#cnb-await-resolve-resolve-parameters}

##### key {#cnb-await-resolve-resolve-parameters-key}

* type: String
* required: true

Pairing ID

##### data {#cnb-await-resolve-resolve-parameters-data}

* type: object
* required: false

Object to be passed

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

```yaml{4-8}
- 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:

```yaml{3-7}
- 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:

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

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

#### Output Results {#cnb-await-resolve-output}

```javascript
{
  // Content returned by resolve
  data
}
```

### apply {#cnb-apply}

`cnb:apply`

Triggers a custom event pipeline in the current repository.

* [Applicable Events](./#cnb-apply-applicable-events)
* [Parameters](./#cnb-apply-parameters)
  * [Environment Variables Related](./#cnb-apply-environment-variables)
  * [Config Value Priority](./#cnb-apply-config-priority)
* [Output Results](./#cnb-apply-output)
* [Configuration Examples](./#cnb-apply-configuration-examples)

#### Applicable Events {#cnb-apply-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 {#cnb-apply-parameters}

* [config](./#cnb-apply-parameters-config)
* [configFrom](./#cnb-apply-parameters-configFrom)
* [event](./#cnb-apply-parameters-event)
* [sync](./#cnb-apply-parameters-sync)
* [continueOnBuildError](./#cnb-apply-parameters-continueOnBuildError)
* [title](./#cnb-apply-parameters-title)

##### config {#cnb-apply-parameters-config}

* type: `String`
* required: `false`

Complete CI configuration file content.

##### configFrom {#cnb-apply-parameters-configFrom}

* type: `String`
* required: `false`

Specifies a local file as the configuration file.

##### event {#cnb-apply-parameters-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 {#cnb-apply-parameters-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 {#cnb-apply-parameters-continueOnBuildError}

* type: `Boolean`
* required: `false`
* default: `false`

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

##### title {#cnb-apply-parameters-title}

* type: `String`
* required: `false`

Custom pipeline title.

#### Environment Variables Related {#cnb-apply-environment-variables}

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 {#cnb-apply-config-priority}

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

1. `config`
2. `configFrom`
3. `.cnb.yml` in the current repository
4. If apply is called in the `pull_request.merged` event, the merged configuration file is used
5. If apply is called in the `pull_request.target` or `pull_request.mergeable` events, the configuration file of the target branch is used
6. 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 {#cnb-apply-output}

```json
{
  "sn": "cnb-i5o-1ht8e12hi", // Build number
  "buildLogUrl": "https://cnb.share.ralphlauren.cn/<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 {#cnb-apply-configuration-examples}

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            configFrom: ./test/.cnb.yml
            event: api_trigger_test
```

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            config: |
              main:
                api_trigger_test: 
                - stages:
                  - name: test
                    script: echo test

            event: api_trigger_test
```

```yaml title=".cnb.yml"
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
```

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            configFrom: .xxx.yml
            event: api_trigger_test
            sync: true
```

### Trigger {#cnb-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](#cnb-trigger-applicable-events)
* [Parameters](#cnb-trigger-parameters)
* [Output Results](#cnb-trigger-output)
* [Configuration Examples](#cnb-trigger-configuration-examples)
  * [Basic Usage](#cnb-trigger-configuration-examples-basic-usage)

#### Applicable Events {#cnb-trigger-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Parameters {#cnb-trigger-parameters}

* [token](#cnb-trigger-parameters-token)
* [slug](#cnb-trigger-parameters-slug)
* [event](#cnb-trigger-parameters-event)
* [branch](#cnb-trigger-parameters-branch)
* [sha](#cnb-trigger-parameters-sha)
* [env](#cnb-trigger-parameters-env)
* [sync](#cnb-trigger-parameters-sync)
* [continueOnBuildError](#cnb-trigger-parameters-continueOnBuildError)
* [title](#cnb-trigger-parameters-title)

##### token {#cnb-trigger-parameters-token}

* type: `String`
* default: Environment variable [CNB\_TOKEN](../build-in-env.md#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 {#cnb-trigger-parameters-slug}

* type: `String`
* required: `true`

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

##### event {#cnb-trigger-parameters-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 {#cnb-trigger-parameters-branch}

* type: `String`
* required: `false`

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

##### sha {#cnb-trigger-parameters-sha}

* type: `String`
* required: `false`

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

##### env {#cnb-trigger-parameters-env}

* type: [TriggerEnv](#cnb-trigger-parameters-type-definitions-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 {#cnb-trigger-parameters-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 {#cnb-trigger-parameters-continueOnBuildError}

* type: `Boolean`
* required: `false`
* default: `false`

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

##### title {#cnb-trigger-parameters-title}

* type: `String`
* required: `false`

Custom pipeline title.

##### Type Definitions {#cnb-trigger-parameters-type-definitions}

###### TriggerEnv {#cnb-trigger-parameters-type-definitions-TriggerEnv}

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

#### Output Results {#cnb-trigger-output}

```json
{
  "sn": "cnb-i5o-1ht8e12hi", // Build number
  "buildLogUrl": "https://cnb.share.ralphlauren.cn/<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 {#cnb-trigger-configuration-examples}

##### Basic Usage {#cnb-trigger-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.

```yaml title="cnb.yml"
main:
  push:
    - stages:
        - name: trigger
          type: cnb:trigger
          imports: https://cnb.share.ralphlauren.cn/<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}

`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](#cnb-read-file-applicable-events)
* [Parameters](#cnb-read-file-parameters)
* [Output Results](#cnb-read-file-output)
* [Configuration Examples](#cnb-read-file-configuration-examples)

#### Applicable Events {#cnb-read-file-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Parameters {#cnb-read-file-parameters}

##### filePath

* type: String
* required: true

Local file path.

#### Output Results {#cnb-read-file-output}

```json
{
  // Object read from the file
}
```

#### Configuration Examples {#cnb-read-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.

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

```yaml title="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}

`cnb:destroy-token`

A [CNB\_TOKEN](../build-in-env.md#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](./#cnb-read-file-applicable-events)
* [Parameters](./#cnb-read-file-parameters)
* [Output](./#cnb-read-file-output)
* [Configuration Examples](./#cnb-read-file-configuration-examples)

#### Applicable Events {#cnb-destroy-token-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Parameters {#cnb-destroy-token-parameters}

None

#### Output {#cnb-destroy-token-output}

None

#### Configuration Examples {#cnb-destroy-token-configuration-examples}

Proactively destroy the CNB\_TOKEN after use in the pipeline to reduce the risk of CNB\_TOKEN misuse.

```yaml title="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}

`vscode:go`

Difference in configuring this built-in task for Workspaces:

* \==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, Workspaces 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](#vscode-go-applicable-events)
* [Output Results](#vscode-go-output)
* [Configuration Examples](#vscode-go-configuration-examples)

#### Applicable Events {#vscode-go-applicable-events}

* `vscode`
* `branch.create`
* `api_trigger`
* `web_trigger`

#### Output Results {#vscode-go-output}

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

#### Configuration Examples {#vscode-go-configuration-examples}

```yaml title=".cnb.yml"
$:
  # vscode event: specifically for starting Workspaces 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}

`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](../trigger-rule.md#pull_request-mergeable).

* [Applicable Events](#git-auto-merge-applicable-events)
* [Parameters](#git-auto-merge-parameters)
* [Output Results](#git-auto-merge-output)
* [Configuration Examples](#git-auto-merge-configuration-examples)
  * [Stand-alone Usage](#git-auto-merge-configuration-examples-standalone-usage)
  * [Used with Target Branch Push Event](#git-auto-merge-configuration-examples-used-with-target-branch-push-event)
* [Best Practices](#git-auto-merge-best-practices)
  * [Using Squash Auto-Merge](#git-auto-merge-best-practices-using-squash-auto-merge)
  * [Automatically Selecting Merge Type](#git-auto-merge-best-practices-using-auto-automatically-select-merge-type)
  * [Establishing Dedicated CR Group for Cross-Review Auto-Merge](#git-auto-merge-best-practices-establishing-dedicated-cr-group-cross-review-auto-merge)

#### Applicable Events {#git-auto-merge-applicable-events}

`pull_request.mergeable`

#### Parameters {#git-auto-merge-parameters}

* [mergeType](#git-auto-merge-parameters-mergeType)
* [mergeCommitMessage](#git-auto-merge-parameters-mergeCommitMessage)
* [mergeCommitFooter](#git-auto-merge-parameters-mergeCommitFooter)
* [removeSourceBranch](#git-auto-merge-parameters-removeSourceBranch)
* [ignoreAssignee](#git-auto-merge-parameters-ignoreAssignee)

##### mergeType {#git-auto-merge-parameters-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 {#git-auto-merge-parameters-mergeCommitMessage}

* type: `String`
* required: `false`

Commit message for the merge.

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

2. 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:

```txt
chore: merge node(merged by CNB)

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

3. 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:

```yaml title=".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

```txt
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

```txt
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:

```txt
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:

4. It can also be directly specified

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

```yaml title=".cnb.yml"
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeCommitMessage: $CNB_PULL_REQUEST_TITLE
```

##### mergeCommitFooter {#git-auto-merge-parameters-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:

```yaml title=".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"
```

```txt
add feature for some jobs

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

##### removeSourceBranch {#git-auto-merge-parameters-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 {#git-auto-merge-parameters-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 {#git-auto-merge-output}

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

#### Configuration Examples {#git-auto-merge-configuration-examples}

##### Stand-alone Usage {#git-auto-merge-configuration-examples-standalone-usage}

```yaml title=".cnb.yml"
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 {#git-auto-merge-configuration-examples-used-with-target-branch-push-event}

```yaml title=".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 {#git-auto-merge-best-practices}

##### Using `squash` Auto-Merge {#git-auto-merge-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.

```yaml title=".cnb.yml"
main:
  review:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: squash
            removeSourceBranch: true
```

##### Automatically Selecting Merge Type with `auto` {#git-auto-merge-best-practices-using-auto-automatically-select-merge-type}

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

```yaml title=".cnb.yml"
main:
  review:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: auto
```

##### Establishing a Dedicated CR Group for Cross-Review Auto-Merge {#git-auto-merge-best-practices-establishing-dedicated-cr-group-cross-review-auto-merge}

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

```yaml title=".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}

`git:issue-update`

\==Update Issue Status==, close or open an issue, and modify issue labels.

* [Applicable Events](#git-issue-update-applicable-events)
* [Work Mechanism](#git-issue-update-work-mechanism)
* [How to Get Issue](#git-issue-update-how-to-get-issue)
* [Including Issue in Commit Logs](#git-issue-update-how-to-include-issue-in-commit-logs)
* [Parameters](#git-issue-update-parameters)
* [Output Results](#git-issue-update-output)
* [Permission Check](./#git-issue-update-permission-check)
* [Configuration Examples](#git-issue-update-configuration-examples)

#### Applicable Events {#git-issue-update-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Work Mechanism {#git-issue-update-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 {#git-issue-update-how-to-get-issue}

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

* **Issue-related events:**

  Retrieve the current Issue.

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

:::tip
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 {#git-issue-update-how-to-include-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.

```shell
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.

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

#### Parameters {#git-issue-update-parameters}

* [fromText](#git-issue-update-parameters-fromText)
* [fromFile](#git-issue-update-parameters-fromFile)
* [state](#git-issue-update-parameters-state)
* [label](#git-issue-update-parameters-label)
* [assignee](./#git-issue-update-parameters-assignee)
* [when](#git-issue-update-parameters-when)
* [lint](#git-issue-update-parameters-lint)
* [defaultColor](#git-issue-update-parameters-defaultColor)
* [prefix](#git-issue-update-parameters-prefix)

##### fromText {#git-issue-update-parameters-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 {#git-issue-update-parameters-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 {#git-issue-update-parameters-state}

* type: [IssueStateMap](#git-issue-update-parameters-type-definitions-issuestatemap)
* required: `false`

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

##### label {#git-issue-update-parameters-label}

* type: [UpdateLabel](#git-issue-update-parameters-type-definitions-updatelabel)
* required: `false`

Description of the operation on labels.

##### assignee {#git-issue-update-parameters-assignee}

* **type**: [UpdateAssignee](#git-parameters-type-definitions-updateassignee)
* **required**: `false`

Description of operations for the `assignee`.

##### when {#git-issue-update-parameters-when}

* type: [IssueUpdateStatus](#git-issue-update-parameters-type-definitions-issueupdatestatus)
* required: `false`

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

##### lint {#git-issue-update-parameters-lint}

* type: [IssueUpdateStatus](#git-issue-update-parameters-type-definitions-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 {#git-issue-update-parameters-defaultColor}

* type: `String`
* required: `false`

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

##### prefix {#git-issue-update-parameters-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 {#git-issue-update-parameters-type-definitions}

###### IssueStateMap {#git-issue-update-parameters-type-definitions-issuestatemap}

* `Enum<String>`: open | close

###### UpdateLabel {#git-issue-update-parameters-type-definitions-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.

###### UpdateAssignee {#git-parameters-type-definitions-updateassignee}

* add
  * type: `Array<String>` | `String`
  * required: `false`

List of assignees to add.

* remove
  * type: `Array<String>` | `String`
  * required: `false`

List of assignees to remove.

###### IssueUpdateStatus {#git-issue-update-parameters-type-definitions-issueupdatestatus}

* label
  * type: `Array<String>` | `String`
  * required: `false`

Labels, where multiple values are connected by `or`.

#### Output Results {#git-issue-update-output}

```javascript
{
    issues // List of issues
}
```

#### Permission Check {#git-issue-update-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 {#git-issue-update-configuration-examples}

* After merging into main, update labels

```yaml title=".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

```yaml title=".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

```yaml title=".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}

`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](#git-reviewer-applicable-events)
* [Parameters](#git-reviewer-parameters)
* [Output Results](#git-reviewer-output)
* [Configuration Examples](#git-reviewer-configuration-examples)
* [Best Practices](#git-reviewer-best-practices)

#### Applicable Events {#git-reviewer-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 {#git-reviewer-parameters}

* [type](#git-reviewer-parameters-type)
* [reviewers](#git-reviewer-parameters-reviewers)
* [count](#git-reviewer-parameters-count)
* [exclude](#git-reviewer-parameters-exclude)
* [reviewersConfig](#git-reviewer-parameters-reviewersConfig)
* [role](#git-reviewer-parameters-role)
* [skip\_on\_wip](./#git-reviewer-parameters-skip_on_wip)

##### type {#git-reviewer-parameters-type}

* type: [REVIEW\_OPERATION\_TYPE](#git-reviewer-parameters-type-definitions-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 {#git-reviewer-parameters-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 {#git-reviewer-parameters-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 {#git-reviewer-parameters-exclude}

* type: `Array<String>` | `String`
* required: `false`

Exclude specified users.

##### reviewersConfig {#git-reviewer-parameters-reviewersConfig}

* type: [IReviewersConfig](#git-reviewer-parameters-type-definitions-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):

```json
{
  "reviewersConfig": "config.json"
}
```

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

* Object format, passing the file reviewers configuration:

```json
{
  "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 {#git-reviewer-parameters-role}

* type: [ROLE\_TYPE](#git-reviewer-parameters-type-definitions-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 {#git-reviewer-parameters-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 {#git-reviewer-parameters-type-definitions}

###### REVIEW\_OPERATION\_TYPE {#git-reviewer-parameters-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 {#git-reviewer-parameters-type-definitions-IReviewersConfig}

```javascript
{
    [key: String]: String
}
```

###### ROLE\_TYPE {#git-reviewer-parameters-type-definitions-ROLE\_TYPE}

* `Enum<String>`: Developer | Master | Owner

#### Output Results {#git-reviewer-output}

Output result for adding reviewers:

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

Output result for adding assignees:

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

#### Configuration Examples {#git-reviewer-configuration-examples}

* Adding reviewers and assignees:

```yaml title=".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:

```yaml title=".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:

```yaml title=".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:

```yaml title=".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:

```yaml title=".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:

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: Add Reviewer
          type: git:reviewer
          options:
            type: add-reviewer-from-repo-members
```

#### Best Practices {#git-reviewer-best-practices}

Establish a dedicated code review (CR) group for cross-review and automatic merging.

1. Randomly select N reviewers for a PR and notify the group.
2. Automatically merge after the review is approved.
3. Record reviewer information in the commit message.
4. Configure Git to automatically merge based on multi-reviewer approval policies for cross-review.

```yaml title=".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}

`git:release`

\==Publish a Release for the repository==

* [Applicable Events](#git-release-applicable-events)
* [Parameters](#git-release-parameters)
* [Output Results](#git-release-output)
* [Configuration Examples](#git-release-configuration-examples)

#### Applicable Events {#git-release-applicable-events}

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

#### Parameters {#git-release-parameters}

* [overlying](#git-release-parameters-overlying)
* [tag](#git-release-parameters-tag)
* [title](#git-release-parameters-title)
* [description](#git-release-parameters-description)
* [descriptionFromFile](#git-release-parameters-descriptionFromFile)
* [preRelease](#git-release-parameters-preRelease)
* [latest](#git-release-parameters-latest)

:::tip
This built-in task does not support uploading attachments. You can use the [cnbcool/attachments](../../../plugin/#public/cnbcool/attachments) task to upload attachments.
:::

##### overlying {#git-release-parameters-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.
:::

##### tag {#git-release-parameters-tag}

* type: `String` | `Number`
* required: `false`

Tag name corresponding to the `release`, not required.

For `tag_push` events, this is not needed as it directly takes the Tag name triggering the `tag_push` event.

For non-`tag_push` events, this is required as the Tag name corresponding to the Release.

##### title {#git-release-parameters-title}

* type: `String`
* required: `false`
* default: Tag name

Title of the Release.

##### description {#git-release-parameters-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 {#git-release-parameters-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 {#git-release-parameters-preRelease}

* type: `Boolean`
* required: `false`
* default: `false`

Whether to set the `release` as a pre-release.

##### latest {#git-release-parameters-latest}

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

Whether to set the Release as the latest version.

#### Output Results {#git-release-output}

None

#### Configuration Examples {#git-release-configuration-examples}

* Generate changelog and automatically update Release description:

```yaml title=".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:

```yaml title=".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}

`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](./#git-pr-commit-message-preset-events)
* [Parameters](./#git-pr-commit-message-preset-parameters)
* [Output Results](./#git-pr-commit-message-preset-output)
* [Configuration Example](./#git-pr-commit-message-preset-configuration-examples)

#### Applicable Events {#git-pr-commit-message-preset-events}

* `pull_request`
* `pull_request.target`
* `pull_request.update`
* `pull_request.mergeable`
* `pull_request.approved`
* `pull_request.changes_requested`

#### Parameters {#git-pr-commit-message-preset-parameters}

* [message](./#git-pr-commit-message-preset-parameters-message)

##### message {#git-pr-commit-message-preset-parameters-message}

* type: `String`
* required: `true`

Pre-set commit message for the PR.

#### Output Results {#git-pr-commit-message-preset-output}

None

#### Configuration Example {#git-pr-commit-message-preset-configuration-examples}

```yaml title=".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}

`git:pr-update`

\==Updating PR Labels and Title==

* [Applicable Events](./#git-pr-update-applicable-events)
* [How to Get PR ID](./#git-pr-update-how-to-get-pr)
* [How to Include PR ID in Commit Logs](./#git-pr-update-how-to-include-pr-id-in-commit-logs)
* [Parameters](./#git-pr-update-parameters)
* [Output Results](./#git-pr-update-output)
* [Permission Check](./#git-pr-update-permission-check)
* [Configuration Examples](./#git-pr-update-configuration-examples)

#### Applicable Events {#git-pr-update-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### How to Get PR ID {#git-pr-update-how-to-get-pr}

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

:::tip
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 {#git-pr-update-parameters}

* [fromText](./#git-pr-update-parameters-fromtext)
* [fromFile](./#git-pr-update-parameters-fromfile)
* [label](./#git-pr-update-parameters-label)
* [title](./#git-pr-update-parameters-title)
* [defaultColor](./#git-pr-update-parameters-defaultcolor)

##### fromText {#git-pr-update-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 {#git-pr-update-parameters-fromfile}

* type: `String`
* required: `false`

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

##### label {#git-pr-update-parameters-label}

* type: [UpdateLabel](#git-parameters-type-definitions-UpdateLabel)
* required: `false`

Labels to be added or removed.

##### title {#git-pr-update-parameters-title}

* type: `String`
* required: `false`

The title of the PR.

##### defaultColor {#git-pr-update-parameters-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 {#git-pr-update-output}

```javascript
{
    pullRequests // List of modified PRs
}
```

#### Permission Check {#git-pr-update-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 {#git-pr-update-configuration-examples}

The following pipeline implements the following functionalities:

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

```yaml title=".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}

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

:::tip
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](#testing-coverage-applicable-events)
* [Full Coverage](#testing-coverage-full-coverage)
* [Incremental Coverage](#testing-coverage-incremental-coverage)
* [Parameters](#testing-coverage-parameters)
* [Output Results](#testing-coverage-output)
* [Configuration Examples](#testing-coverage-configuration-examples)

#### Applicable Events {#testing-coverage-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Full Coverage {#testing-coverage-full-coverage}

![coverage](//cnb.share.ralphlauren.cn/svg/badge/coverage?message=18.67%25\&color=l2)
![coverage](//cnb.share.ralphlauren.cn/svg/badge/coverage?message=38.67%25\&color=l3)
![coverage](//cnb.share.ralphlauren.cn/svg/badge/coverage?message=58.67%25\&color=l4)
![coverage](//cnb.share.ralphlauren.cn/svg/badge/coverage?message=78.67%25\&color=l5)

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

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

#### Incremental Coverage {#testing-coverage-incremental-coverage}

![coverage-pr](//cnb.share.ralphlauren.cn/svg/badge/coverage%20%40pr?message=18.67%25\&color=l2)
![coverage-pr](//cnb.share.ralphlauren.cn/svg/badge/coverage%20%40pr?message=38.67%25\&color=l3)
![coverage-pr](//cnb.share.ralphlauren.cn/svg/badge/coverage%20%40pr?message=58.67%25\&color=l4)
![coverage-pr](//cnb.share.ralphlauren.cn/svg/badge/coverage%20%40pr?message=78.67%25\&color=l5)

#### Parameters {#testing-coverage-parameters}

* [key](#testing-coverage-parameters-key)
* [name](#testing-coverage-parameters-name)
* [pattern](#testing-coverage-parameters-pattern)
* [lines](#testing-coverage-parameters-lines)
* [diffLines](#testing-coverage-parameters-diffLines)
* [allowExts](#testing-coverage-parameters-allowExts)
* [lang](#testing-coverage-parameters-lang)
* [breakIfNoCoverage](#testing-coverage-parameters-breakIfNoCoverage)

##### key {#testing-coverage-parameters-key}

* type: `String`
* required: `false`

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

##### name {#testing-coverage-parameters-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 {#testing-coverage-parameters-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 {#testing-coverage-parameters-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 {#testing-coverage-parameters-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 {#testing-coverage-parameters-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 {#testing-coverage-parameters-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 {#testing-coverage-parameters-breakIfNoCoverage}

* type: `Boolean`
* required: `false`

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

#### Output Results {#testing-coverage-output}

```json
{
  // 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 {#testing-coverage-configuration-examples}

```yaml title=".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}

`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](#artifact-remove-tag-applicable-events)
* [Parameters](#artifact-remove-tag-parameters)
* [Configuration Examples](#artifact-remove-tag-configuration-examples)

#### Applicable Events {#artifact-remove-tag-applicable-events}

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

#### Parameters {#artifact-remove-tag-parameters}

* [name](#artifact-remove-tag-parameters-name)
* [tags](#artifact-remove-tag-parameters-tags)
* [type](#artifact-remove-tag-parameters-type)

##### name {#artifact-remove-tag-parameters-name}

* type: `String`
* required: `true`

Artifact package name

##### tags {#artifact-remove-tag-parameters-tags}

* type: `Array<string>`
* required: `true`

##### type {#artifact-remove-tag-parameters-type}

* type: `String`
* required: `false`
* default: `docker`

Artifact type, currently only supports Docker and Helm

#### Configuration Examples {#artifact-remove-tag-configuration-examples}

```yaml title=".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.

### status-update {#tapd-status-update}

`tapd:status-update`

\==Update the status of TAPD-associated items (story, task, or bug)==

* [Applicable Events](./#tapd-status-update-applicable-events)
* [Parameters](./#tapd-status-update-parameters)
* [Configuration Examples](./#tapd-status-update-configuration-examples)

#### Applicable Events {#tapd-status-update-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Parameters {#tapd-status-update-parameters}

* [status](./#tapd-status-update-parameters-status)
* [when](./#tapd-status-update-parameters-when)
* [type](./#tapd-status-update-parameters-type)
* [fromText](./#tapd-status-update-parameters-from-text)

##### status {#tapd-status-update-parameters-status}

* Type: `String`
* Required: `true`\
  Target status.

##### when {#tapd-status-update-parameters-when}

* Type: `String` | `Array<String>`
* Required: `false`

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

##### type {#tapd-status-update-parameters-type}

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

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

##### fromText {#tapd-status-update-parameters-from-text}

* Type: `String`
* Required: `false`

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

#### Configuration Examples {#tapd-status-update-configuration-examples}

1. Update the status of all TAPD-associated items:

```yaml title=".cnb.yml"  
main:
  push:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: developing
```

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

```yaml title=".cnb.yml"  
main:
  pull_request.merged:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: Completed
            when:
              - developing
            type: story
```

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

```yaml title=".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
```

### comment {#tapd-comment}

`tapd:comment`

\==Submit a comment for TAPD-associated items (story, task, or bug)==

* [Applicable Events](./#tapd-comment-applicable-events)
* [Parameters](./#tapd-comment-parameters)
* [Configuration Examples](./#tapd-comment-configuration-examples)

#### Applicable Events {#tapd-comment-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### Parameters {#tapd-comment-parameters}

* [comment](./#tapd-comment-parameters-comment)
* [when](./#tapd-comment-parameters-when)
* [type](./#tapd-comment-parameters-type)
* [fromText](./#tapd-status-update-parameters-from-text)

##### comment {#tapd-comment-parameters-comment}

* Type: `String`
* Required: `true`

Comment content.

##### when {#tapd-comment-parameters-when}

* Type: `String` | `Array<String>`
* Required: `false`

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

##### type {#tapd-comment-parameters-type}

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

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

##### fromText {#tapd-comment-parameters-from-text}

* Type: `String`
* Required: `false`

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

#### Configuration Examples {#tapd-comment-configuration-examples}

1. Comment on all TAPD-associated items:

```yaml title=".cnb.yml"  
main:
  push:
    - stages:
        - name: add tapd comment
          type: tapd:comment
          options:
            comment: Start development
```

2. Comment on TAPD-associated items that meet specific conditions:

```yaml title=".cnb.yml"  
main:
  pull_request.merged:
    - stages:
        - name: add tapd comment
          type: tapd:comment
          options:
            comment: Merged
            when:
              - developing
            type: story
```

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

```yaml title=".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
```

## knowledge

### update {#knowledge-update}

`knowledge:update`

\==Update knowledge base==, used to build Issues, repository documents, etc. into the knowledge base.

* [Applicable Events](./#knowledge-update-applicable-events)
* [Parameters](./#knowledge-update-parameters)
* [Configuration Examples](./#knowledge-update-configuration-examples)

#### Applicable Events {#knowledge-update-applicable-events}

[All Events](../trigger-rule.md#trigger-event)

#### How it works {#knowledge-update-how-it-works}

Fetch repository Issues & documents -> chunking -> vectorization -> into knowledge base

#### Parameters {#knowledge-update-parameters}

* [include](./#knowledge-update-parameters-include)
* [exclude](./#knowledge-update-parameters-exclude)
* [chunkSize](./#knowledge-update-parameters-chunkSize)
* [chunkOverlap](./#knowledge-update-parameters-chunkOverlap)
* [embeddingModel](./#knowledge-update-parameters-embeddingModel)
* [issueSyncEnabled](./#knowledge-update-parameters-issueSyncEnabled)
* [issueState](./#knowledge-update-parameters-issueState)
* [issueLabels](./#knowledge-update-parameters-issueLabels)
* [issueExcludeLabels](./#knowledge-update-parameters-issueExcludeLabels)
* [forceRebuild](./#knowledge-update-parameters-forceRebuild)
* [ignoreProcessFailures](./#knowledge-update-parameters-ignoreProcessFailures)

##### include {#knowledge-update-parameters-include}

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

Specify which files to include, using `Glob` pattern matching. Defaults to `**/**.md` (all Markdown files). Supports arrays or comma-separated values. Supported file types: .md, .mdx, .docx, .txt, .pdf.

##### exclude {#knowledge-update-parameters-exclude}

* type: `String` | `Array<String>`
* required: `false`

Specify files to exclude using `Glob` patterns. By default, nothing is excluded. Supports arrays or comma-separated values.

##### chunkSize {#knowledge-update-parameters-chunkSize}

* type: `Number`
* required: `false`
* default: `1500`

Specify the text chunk size.

##### chunkOverlap {#knowledge-update-parameters-chunkOverlap}

* type: `Number`
* required: `false`
* default: `0`

Specify the overlapping token count between two adjacent chunks.

##### embeddingModel {#knowledge-update-parameters-embeddingModel}

* type: `String`
* required: `false`
* default: `hunyuan`

Embedding model. Currently, only `hunyuan` is supported.

##### issueSyncEnabled {#knowledge-update-parameters-issueSyncEnabled}

* type: `Boolean`
* required: `false`
* default: `true`

Whether to enable Issue sync. If enabled, Issues from the repository will be automatically pulled and added to the knowledge base.

##### issueState {#knowledge-update-parameters-issueState}

* type: `String`
* required: `false`

Only sync Issues with the specified state. Defaults to all. Optional values: `open` | `closed`.

##### issueLabels {#knowledge-update-parameters-issueLabels}

* type: `String` | `Array<String>`
* required: `false`

Only sync Issues with the specified labels. Defaults to all. Supports arrays or comma-separated values.

##### issueExcludeLabels {#knowledge-update-parameters-issueExcludeLabels}

* type: `String` | `Array<String>`
* required: `false`

Exclude Issues with the specified labels. By default, no Issues are excluded. Supports arrays or comma-separated values. When overlapping with `issueLabels`, exclude takes priority.

##### forceRebuild {#knowledge-update-parameters-forceRebuild}

* type: `Boolean`
* required: `false`
* default: `false`

Whether to delete and rebuild the knowledge base. When set to `true`, the knowledge base is deleted and created afresh.

##### ignoreProcessFailures {#knowledge-update-parameters-ignoreProcessFailures}

* type: `Boolean`
* required: `false`
* default: `false`

Whether to ignore document processing failures. If set to `true`, the knowledge base will update even if some documents failed to process.

#### Configuration Examples {#knowledge-update-configuration-examples}

##### Basic Usage {#knowledge-update-configuration-examples-basic-usage}

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

## npc

### go {#npc-go}

`npc:go`

Executes an AI coding agent task in a specified Docker image when an NPC role is mentioned in an Issue or PR comment.
You can install CLI tools and Skills required by the NPC at runtime in the image, such as [CNB Skill](https://cnb.cool/cnb/skills/cnb-skill). For more NPC configuration, see [NPC Events](../npc.md).

* [Applicable Events](./#npc-go-applicable-events)
* [Parameters](./#npc-go-parameters)
* [Configuration Examples](./#npc-go-configuration-examples)

#### Applicable Events {#npc-go-applicable-events}

`issue.comment@npc`, `pull_request.comment@npc`, `api_trigger`, `crontab`

#### Parameters {#npc-go-parameters}

:::warning
The following parameters only take effect in `api_trigger` and `crontab` events. No configuration is needed for other events.
:::

* [role](./#npc-go-parameters-role)
* [systemPrompt](./#npc-go-parameters-systemPrompt)
* [userPrompt](./#npc-go-parameters-userPrompt)

##### role {#npc-go-parameters-role}

* type: `String`
* required: `true`

NPC role name. It must be defined in the `roles` field of the NPC section in the `.cnb/settings.yml` file. See [UI Customization](../repo/settings.md) for reference.

##### systemPrompt {#npc-go-parameters-systemPrompt}

* type: `String`
* required: `true`

NPC system prompt.

##### userPrompt {#npc-go-parameters-userPrompt}

* type: `String`
* required: `true`

NPC user input, mainly used for the user to describe tasks to the NPC.

#### Configuration Examples {#npc-go-configuration-examples}

```yaml title=".cnb.yml"
$:
  issue.comment@npc:
    - docker:
        # Specify image containing CLI tools and Skills required by the NPC
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

# Build and push Docker image
main:
  push:
    - services:
        - docker
      stages:
        - name: Docker build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: Docker push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
```

Install the Skills and CLI tools required by the NPC in the Dockerfile. The following example installs `cnb-skill` and `cnb-cli`.

```Dockerfile title="Dockerfile"
FROM node:22-bookworm-slim

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

Skills are automatically loaded from the following directories: `~/.agents/skills`, `~/.codebuddy/skills` and their project-level counterparts: `.agents/skills`, `.codebuddy/skills`.

Project-level Skills take priority over user-level Skills. A project-level Skill with the same name will override its user-level counterpart.

The NPC role prompt is defined in the `.cnb/settings.yml` file. See [NPC Events](../npc.md) for details.