cnb:apply

Triggers a custom event pipeline in the current repository.

• Applicable Events
• Parameters
  • Environment Variables Related
  • Config Value Priority
• Output Results
• Configuration Examples

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

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

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

Detailed descriptions for each parameter are provided below.

config

• type: String
• required: false

Complete CI configuration file content.

configFrom

• type: String
• required: false

Specifies a local file as the configuration file.

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

• 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

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

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

title

• type: String
• required: false

Custom pipeline title.

Environment Variables Related

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

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

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

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

Using configFrom to reference a local config file:

.cnb.yml

main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            configFrom: ./test/.cnb.yml
            event: api_trigger_test

Using config for inline configuration:

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

.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):

.cnb.yml

main:
  push:
    - stages:
        - name: trigger
          type: cnb:apply
          options:
            configFrom: .xxx.yml
            event: api_trigger_test
            sync: true