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

触发当前仓库的自定义事件流水线。

* [适用事件](#cnb-apply-applicable-events)
* [参数](#cnb-apply-parameters)
  * [环境变量相关](#cnb-apply-environment-variables)
  * [config 取值优先级](#cnb-apply-config-priority)
* [输出结果](#cnb-apply-output)
* [配置样例](#cnb-apply-configuration-examples)

## 适用事件 {#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`

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

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

* [config](#cnb-apply-parameters-config)：完整的内联 CI 配置文件内容
* [configFrom](#cnb-apply-parameters-configFrom)：指定一个本地文件作为配置文件
* [event](#cnb-apply-parameters-event)：要执行的自定义事件名（默认 `api_trigger`）
* [sync](#cnb-apply-parameters-sync)：是否同步执行，等待子流水线执行成功
* [continueOnBuildError](#cnb-apply-parameters-continueOnBuildError)：同步模式下子流水线失败是否继续执行
* [title](#cnb-apply-parameters-title)：自定义子流水线标题

各参数详细说明如下。

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

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

完整的 CI 配置文件内容。

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

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

指定一个本地文件作为配置文件。

### event {#cnb-apply-parameters-event}

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

要执行的自定义事件名，必须为 `api_trigger` 或以 `api_trigger_` 开头。

### sync {#cnb-apply-parameters-sync}

* type: `Boolean`
* required: `false`
* default: `false`
  是否同步执行。

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

### continueOnBuildError {#cnb-apply-parameters-continueOnBuildError}

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

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

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

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

自定义流水线标题

## 环境变量相关 {#cnb-apply-environment-variables}

传递给新的流水线当前 Job 可见的、业务定义的环境变量。

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

* `APPLY_TRIGGER_BUILD_ID`，含义同 CI 默认环境变量中的 `CNB_BUILD_ID`
* `APPLY_TRIGGER_PIPELINE_ID`，含义同 CI 默认环境变量中的 `CNB_PIPELINE_ID`
* `APPLY_TRIGGER_REPO_SLUG`，含义同 CI 默认环境变量中的 `CNB_REPO_SLUG`
* `APPLY_TRIGGER_REPO_ID`，含义同 CI 默认环境变量中的 `CNB_REPO_ID`
* `APPLY_TRIGGER_USER`，含义同 CI 默认环境变量中的 `CNB_BUILD_USER`
* `APPLY_TRIGGER_BRANCH`，含义同 CI 默认环境变量中的 `CNB_BRANCH`
* `APPLY_TRIGGER_COMMIT`，含义同 CI 默认环境变量中的 `CNB_COMMIT`
* `APPLY_TRIGGER_COMMIT_SHORT`，含义同 CI 默认环境变量中的 `CNB_COMMIT_SHORT`
* `APPLY_TRIGGER_ORIGIN_EVENT`，含义同 CI 默认环境变量中的 `CNB_EVENT`
* `CNB_PULL_REQUEST_ID`，含义同 CI 默认环境变量中的 `CNB_PULL_REQUEST_ID`
* `CNB_PULL_REQUEST_IID`，含义同 CI 默认环境变量中的 `CNB_PULL_REQUEST_IID`
* `CNB_PULL_REQUEST_MERGE_SHA`，含义同 CI 默认环境变量中的 `CNB_PULL_REQUEST_MERGE_SHA`

## Config 取值优先级 {#cnb-apply-config-priority}

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

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

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

## 输出结果 {#cnb-apply-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-apply-configuration-examples}

以下示例展示了 `cnb:apply` 的几种常用方式：

**使用 `configFrom` 引用本地配置文件**：

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

**使用 `config` 内联配置**：

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