cnb:apply

Triggers a custom event pipeline in the current repository.

When to use it: use it when a pipeline needs to run another pipeline of the current repository on demand - for example extracting a piece of pipeline into a reusable api_trigger event that several events can call, optionally waiting for its result synchronously ("sync" mode). No extra token is needed, and the config file can be switched per call, which is how it differs from cnb:trigger.

Difference from other trigger tasks: cnb:trigger triggers a pipeline in another repository, while this task only triggers pipelines of the current repository; cnb:await-resolve coordinates already running concurrent pipelines and never starts a new one.

• 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

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 synchronously and retrieve the exported variables of the triggered pipeline.

.cnb.yml

main:
  api_trigger_test:
    - stages:
        - name: output a variable
          script: echo "##[set-output sub_result=base64,$(echo -e "test string\nsecond line" | base64 -w 0)]"
          exports:
            sub_result: SUB_RESULT

  push:
    - stages:
        - name: trigger pipeline and wait
          type: cnb:apply
          options:
            event: api_trigger_test
            sync: true
          exports:
            lastJobExports: SUB_EXPORTS
            lastJobExports.SUB_RESULT: SUB_RESULT
            sn: SUB_SN
        - name: use variables returned by the triggered pipeline
          script: |
            echo "SUB_EXPORTS: $SUB_EXPORTS"
            echo "SUB_SN: $SUB_SN"
            echo "SUB_RESULT: $SUB_RESULT"

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 the triggered pipeline to complete):

.cnb.yml

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