cnb:trigger

Triggers a custom event pipeline in a specified repository within the current repository (requires permission to trigger the corresponding repository pipeline).

When to use it: use it to link repositories, letting a pipeline in one repository drive a pipeline in another - for example triggering repository B's deployment pipeline once repository A finishes building, optionally waiting synchronously and bringing its exported variables back into the current pipeline. Cross-repository calls need authorization and token management, so cnb:trigger folds this into a single built-in task.

Difference from other trigger tasks: cnb:apply only triggers pipelines of the current repository; cnb:await-resolve coordinates already running concurrent pipelines and never starts a new one.

• Applicable Events
• Parameters
• Output Results
• Configuration Examples
  • Basic Usage

Applicable Events

All Events

Parameters

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

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

Detailed descriptions for each parameter are provided below.

token

• type: String
• default: Environment variable 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

• type: String
• required: true

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

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

• type: String
• required: false

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

sha

• type: String
• required: false

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

env

• type: 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

• 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

• type: Boolean
• required: false
• default: false

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

title

• type: String
• required: false

Custom pipeline title.

Type Definitions

TriggerEnv

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

Output Results

Task results can be exported as environment variables via exports for use in subsequent jobs. The main properties of result are:

Property	Description
sn	Build number of the triggered pipeline
buildLogUrl	Build log URL of the triggered pipeline
message	Trigger result message
buildSuccess	Whether the triggered pipeline succeeded; sync mode (sync: true) only
lastJobExports	All environment variables exported via exports by the last Job of the triggered pipeline; sync mode only

Note

Only sync: true waits for the triggered pipeline to finish and returns buildSuccess and lastJobExports. In async mode (the default), the task does not wait and cannot obtain these two properties.

Export example: trigger a target repository pipeline synchronously and retrieve its exported variables.

.cnb.yml

main:
  push:
    - stages:
        - name: trigger target pipeline and wait
          type: cnb:trigger
          options:
            token: $TOKEN
            slug: a/b
            branch: main
            event: api_trigger_test
            sync: true
          exports:
            lastJobExports: SUB_EXPORTS
            lastJobExports.SUB_RESULT: SUB_RESULT
            sn: SUB_SN
        - name: use variables returned by the target pipeline
          script: |
            echo "SUB_EXPORTS: $SUB_EXPORTS"
            echo "SUB_SN: $SUB_SN"
            echo "SUB_RESULT: $SUB_RESULT"

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.

.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