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

{
  "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

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