CNB 文档

简体中文

English

简体中文

English

外观

cnb:trigger

复制页面

1319 字约 4 分钟

cnb:trigger

在当前仓库中，触发指定仓库的自定义事件流水线（需要有触发对应仓库流水线的权限）。

使用场景：想跨仓库联动、由一个仓库的流水线驱动另一个仓库的流水线时使用——例如 A 仓库构建完成后触发 B 仓库的部署流水线，并可同步等待结果、把导出变量带回当前流水线。 跨仓库调用需要授权与令牌管理，cnb:trigger 把这一步收敛成一个内置任务。

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

适用事件

所有事件

参数

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

  • token：个人访问令牌，用于校验触发权限
  • slug：目标仓库完整路径，如 group/repo
  • event：触发的自定义事件名（api_trigger 或前缀）
  • branch：触发分支，默认目标仓库主分支
  • sha：分支中的 CommitId，默认取最新提交
  • env：传递给目标流水线的环境变量
  • sync：是否同步执行，等待目标流水线成功
  • continueOnBuildError：同步模式下目标流水线失败是否继续
  • title：自定义目标流水线标题

各参数详细说明如下。

token

个人访问令牌。

新流水线触发者为令牌对应用户，会判断有无触发目标仓库流水线权限。

slug

  • type: String
  • required: true

目标仓库的完整路径，如：group/repo。

event

  • type: String
  • required: true

触发的自定义事件名，必须是 api_trigger 或以 api_trigger_ 开头。

目标仓库需配置对应分支、对应事件的流水线才能触发。

branch

  • type: String
  • required: false

触发分支，默认为目标仓库主分支。

sha

  • type: String
  • required: false

触发分支中的 CommitId，默认取 branch 的最新提交记录。

env

触发目标仓库流水线时传递的环境变量。

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

  • API_TRIGGER_BUILD_ID，含义同 CI 默认环境变量中的 CNB_BUILD_ID
  • API_TRIGGER_PIPELINE_ID，含义同 CI 默认环境变量中的 CNB_PIPELINE_ID
  • API_TRIGGER_REPO_SLUG，含义同 CI 默认环境变量中的 CNB_REPO_SLUG
  • API_TRIGGER_REPO_ID，含义同 CI 默认环境变量中的 CNB_REPO_ID
  • API_TRIGGER_USER，含义同 CI 默认环境变量中的 CNB_BUILD_USER
  • API_TRIGGER_BRANCH，含义同 CI 默认环境变量中的 CNB_BRANCH
  • API_TRIGGER_COMMIT，含义同 CI 默认环境变量中的 CNB_COMMIT
  • API_TRIGGER_COMMIT_SHORT，含义同 CI 默认环境变量中的 CNB_COMMIT_SHORT

sync

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

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

continueOnBuildError

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

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

title

  • type: String
  • required: false

自定义流水线标题

类型定义

TriggerEnv

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

输出结果

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

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

注意

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

导出示例：同步触发目标仓库流水线后取回其导出变量。

.cnb.yml
main:
  push:
    - stages:
        - name: 触发目标仓库流水线并等待
          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: 使用目标仓库流水线传回的变量
          script: |
            echo "SUB_EXPORTS: $SUB_EXPORTS"
            echo "SUB_SN: $SUB_SN"
            echo "SUB_RESULT: $SUB_RESULT"

配置样例

基本使用

在当前仓库触发指定仓库 main 分支下事件名为 api_trigger_test 的流水线。

该流水线配置文件使用仓库 main 分支的 .cnb.yml 文件。

使用访问令牌 $TOKEN 查询用户是否有触发目标仓库流水线权限。

.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
© 2026 cnb.cool