---
url: /zh/build/internal-steps/cnb/trigger.md
---
`cnb:trigger`

在当前仓库中，触发指定仓库的自定义事件流水线（需要有触发对应仓库流水线的权限）。

* [适用事件](#cnb-trigger-applicable-events)
* [参数](#cnb-trigger-parameters)
* [输出结果](#cnb-trigger-output)
* [配置样例](#cnb-trigger-configuration-examples)
  * [基本使用](#cnb-trigger-configuration-examples-basic-usage)

## 适用事件 {#cnb-trigger-applicable-events}

[所有事件](../../trigger-rule.md#trigger-event)

## 参数 {#cnb-trigger-parameters}

以下列表先概览 `cnb:trigger` 的全部参数。

* [token](#cnb-trigger-parameters-token)：个人访问令牌，用于校验触发权限
* [slug](#cnb-trigger-parameters-slug)：目标仓库完整路径，如 `group/repo`
* [event](#cnb-trigger-parameters-event)：触发的自定义事件名（`api_trigger` 或前缀）
* [branch](#cnb-trigger-parameters-branch)：触发分支，默认目标仓库主分支
* [sha](#cnb-trigger-parameters-sha)：分支中的 CommitId，默认取最新提交
* [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: 环境变量 [CNB\_TOKEN](../../build-in-env.md#cnb_token)

个人访问令牌。

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

### slug {#cnb-trigger-parameters-slug}

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

目标仓库的完整路径，如：group/repo。

### event {#cnb-trigger-parameters-event}

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

触发的自定义事件名，必须是 `api_trigger` 或以 `api_trigger_` 开头。

目标仓库需配置对应分支、对应事件的流水线才能触发。

### branch {#cnb-trigger-parameters-branch}

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

触发分支，默认为目标仓库主分支。

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

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

触发分支中的 CommitId，默认取 branch 的最新提交记录。

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

* type: [TriggerEnv](#cnb-trigger-parameters-type-definitions-TriggerEnv)
* required: `false`

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

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

* `API_TRIGGER_BUILD_ID`，含义同 CI 默认环境变量中的 `CNB_BUILD_ID`
* `API_TRIGGER_PIPELINE_ID`，含义同 CI 默认环境变量中的 `CNB_PIPELINE_ID`
* `API_TRIGGER_REPO_SLUG`，含义同 CI 默认环境变量中的 `CNB_REPO_SLUG`
* `API_TRIGGER_REPO_ID`，含义同 CI 默认环境变量中的 `CNB_REPO_ID`
* `API_TRIGGER_USER`，含义同 CI 默认环境变量中的 `CNB_BUILD_USER`
* `API_TRIGGER_BRANCH`，含义同 CI 默认环境变量中的 `CNB_BRANCH`
* `API_TRIGGER_COMMIT`，含义同 CI 默认环境变量中的 `CNB_COMMIT`
* `API_TRIGGER_COMMIT_SHORT`，含义同 CI 默认环境变量中的 `CNB_COMMIT_SHORT`

### sync {#cnb-trigger-parameters-sync}

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

是否同步执行。同步模式下会等待本次 trigger 流水线执行成功后，再执行下一个任务。

### continueOnBuildError {#cnb-trigger-parameters-continueOnBuildError}

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

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

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

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

自定义流水线标题

### 类型定义 {#cnb-trigger-parameters-type-definitions}

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

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

## 输出结果 {#cnb-trigger-output}

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

## 配置样例 {#cnb-trigger-configuration-examples}

### 基本使用 {#cnb-trigger-configuration-examples-basic-usage}

在当前仓库触发指定仓库 main 分支下事件名为 `api_trigger_test` 的流水线。

该流水线配置文件使用仓库 main 分支的 `.cnb.yml` 文件。

使用访问令牌 `$TOKEN` 查询用户是否有触发目标仓库流水线权限。

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