---
url: /en/build/internal-steps/cnb/apply.md
---
`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}

The list below gives an overview of all `cnb:apply` parameters.

* [config](#cnb-apply-parameters-config): Full inline CI configuration content
* [configFrom](#cnb-apply-parameters-configFrom): Specify a local file as the configuration file
* [event](#cnb-apply-parameters-event): Custom event to run (defaults to `api_trigger`)
* [sync](#cnb-apply-parameters-sync): Sync mode; wait until the triggered pipeline succeeds
* [continueOnBuildError](#cnb-apply-parameters-continueOnBuildError):
  In sync mode, continue on triggered build failure
* [title](#cnb-apply-parameters-title): Custom title of the triggered pipeline

Detailed descriptions for each parameter are provided below.

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

## Configuration Examples {#cnb-apply-configuration-examples}

The following examples show common ways to use `cnb:apply`:

**Using `configFrom` to reference a local config file**:

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

**Using `config` for inline configuration**:

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

**Trigger other events defined in the current config file**:

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

**Sync mode (wait for sub-pipeline to complete)**:

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