cnb:apply

1373 字约 5 分钟

cnb:apply

触发当前仓库的自定义事件流水线。

使用场景：想在流水线中按需再跑一段当前仓库的流水线时使用——例如把一段流水线抽成可复用的 api_trigger 事件，供多个事件按需调用，并可同步等待其执行结果。无需额外令牌、可在需要时切换配置文件，是它相比 cnb:trigger 的差异。

与其他触发方式的区别：cnb:trigger 用于触发其他仓库的流水线，本任务只触发当前仓库的流水线；cnb:await-resolve 则是在已运行的多个并发流水线之间做等待与通知，不会新建流水线。

适用事件
参数
- 环境变量相关
- config 取值优先级
输出结果
配置样例

适用事件

push
commit.add
branch.create
pull_request.target
pull_request.mergeable
tag_push
pull_request.merged
api_trigger
web_trigger
crontab
tag_deploy

参数

以下列表先概览 cnb:apply 的全部参数。

config：完整的内联 CI 配置文件内容
configFrom：指定一个本地文件作为配置文件
event：要执行的自定义事件名（默认 api_trigger）
sync：是否同步执行，等待触发的流水线执行成功
continueOnBuildError：同步模式下触发的流水线失败是否继续执行
title：自定义触发的流水线标题

各参数详细说明如下。

config

type: String
required: false

完整的 CI 配置文件内容。

configFrom

type: String
required: false

指定一个本地文件作为配置文件。

event

type: String
required: false
default: api_trigger

要执行的自定义事件名，必须为 api_trigger 或以 api_trigger_ 开头。

sync

type: Boolean
required: false
default: false 是否同步执行。

同步模式下会等待本次 apply 流水线执行成功，再执行下一个任务。

continueOnBuildError

type: Boolean
required: false
default: false

同步模式下，触发的流水线构建失败时，是否继续执行下个任务。

title

type: String
required: false

自定义流水线标题

环境变量相关

传递给新的流水线当前 Job 可见的、业务定义的环境变量。

默认值中有如下环境变量，用户无法覆盖：

APPLY_TRIGGER_BUILD_ID，含义同 CI 默认环境变量中的 CNB_BUILD_ID
APPLY_TRIGGER_PIPELINE_ID，含义同 CI 默认环境变量中的 CNB_PIPELINE_ID
APPLY_TRIGGER_REPO_SLUG，含义同 CI 默认环境变量中的 CNB_REPO_SLUG
APPLY_TRIGGER_REPO_ID，含义同 CI 默认环境变量中的 CNB_REPO_ID
APPLY_TRIGGER_USER，含义同 CI 默认环境变量中的 CNB_BUILD_USER
APPLY_TRIGGER_BRANCH，含义同 CI 默认环境变量中的 CNB_BRANCH
APPLY_TRIGGER_COMMIT，含义同 CI 默认环境变量中的 CNB_COMMIT
APPLY_TRIGGER_COMMIT_SHORT，含义同 CI 默认环境变量中的 CNB_COMMIT_SHORT
APPLY_TRIGGER_ORIGIN_EVENT，含义同 CI 默认环境变量中的 CNB_EVENT
CNB_PULL_REQUEST_ID，含义同 CI 默认环境变量中的 CNB_PULL_REQUEST_ID
CNB_PULL_REQUEST_IID，含义同 CI 默认环境变量中的 CNB_PULL_REQUEST_IID
CNB_PULL_REQUEST_MERGE_SHA，含义同 CI 默认环境变量中的 CNB_PULL_REQUEST_MERGE_SHA

Config 取值优先级

按以下顺序依次取值，取到为止：

config
configFrom
当前仓库 .cnb.yml
若在 pull_request.merged 事件中调用 apply 内置任务，取合并后的配置文件
若在 pull_request.target、pull_request.mergeable 事件中调用 apply 内置任务，取目标分支的配置文件
其他情况取当前分支配置文件

configFrom 只支持本地文件如 ./test/.cnb.yml，远程文件可先自行下到本地。

输出结果

任务结果可通过 exports 导出为环境变量，供后续任务使用。 result 的主要属性如下：

属性	说明
sn	触发流水线的构建号
buildLogUrl	触发流水线的构建日志链接
message	触发结果信息
buildSuccess	触发流水线是否构建成功，仅同步模式（`sync: true`）存在
lastJobExports	触发流水线最后一个 Job 通过 `exports` 导出的全部环境变量，仅同步模式存在

注意

只有 sync: true 才会等待触发的流水线执行完成，并返回 buildSuccess 与 lastJobExports；异步模式（默认）下不等待，也拿不到这两个属性。

导出示例：同步触发后取回被触发流水线的导出变量。

.cnb.yml
main:
  api_trigger_test:
    - stages:
        - name: 输出变量
          script: echo "##[set-output sub_result=base64,$(echo -e "测试字符串\ntest string" | base64 -w 0)]"
          exports:
            sub_result: SUB_RESULT

  push:
    - stages:
        - name: 触发流水线并等待
          type: cnb:apply
          options:
            event: api_trigger_test
            sync: true
          exports:
            lastJobExports: SUB_EXPORTS
            lastJobExports.SUB_RESULT: SUB_RESULT
            sn: SUB_SN
        - name: 使用被触发流水线传回的变量
          script: |
            echo "SUB_EXPORTS: $SUB_EXPORTS"
            echo "SUB_SN: $SUB_SN"
            echo "SUB_RESULT: $SUB_RESULT"

配置样例

以下示例展示了 cnb:apply 的几种常用方式：

使用 configFrom 引用本地配置文件：

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

使用 config 内联配置：

.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

触发当前配置文件中定义的其他事件：

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

同步模式（等待触发的流水线执行完成）：

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