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

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

* [token](#cnb-trigger-parameters-token): Personal access token used to check trigger permission
* [slug](#cnb-trigger-parameters-slug): Full path of the target repository, e.g. `group/repo`
* [event](#cnb-trigger-parameters-event): Custom event to trigger (`api_trigger` or prefixed)
* [branch](#cnb-trigger-parameters-branch): Branch to trigger; defaults to the target repo default branch
* [sha](#cnb-trigger-parameters-sha): CommitId on the branch; defaults to the latest commit
* [env](#cnb-trigger-parameters-env): Environment variables passed to the target pipeline
* [sync](#cnb-trigger-parameters-sync): Sync mode; wait until the target pipeline succeeds
* [continueOnBuildError](#cnb-trigger-parameters-continueOnBuildError):
  In sync mode, continue on target build failure
* [title](#cnb-trigger-parameters-title): Custom title of the target pipeline

Detailed descriptions for each parameter are provided below.

### 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.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-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.cool/<your-repo-slug>/-/blob/main/xxx/envs.yml
          options:
            token: $TOKEN
            slug: a/b
            branch: main
            event: api_trigger_test
```