跳到主要内容

除了 push，还能怎么触发

push 是最常用的触发方式，但不是唯一的。四种"主动触发"各有明确场景。

一、页面上放个按钮：web_trigger​

给不熟悉命令行的人一个"点一下就发布"的入口。

配置分两处：.cnb/web_trigger.yml 定义按钮，.cnb.yml 定义按钮点击后跑什么。

.cnb/web_trigger.yml
branch:
  - reg: ^release
    buttons:
      - name: 发布
        event: web_trigger_release
        inputs:
          version:
            name: 版本号
            type: input
            required: true
            default: 1.0.0
          env:
            name: 环境
            type: select
            default: staging
            options:
              - name: 开发环境
                value: dev
              - name: 预发布
                value: staging
              - name: 生产环境
                value: production
.cnb.yml
$:
  web_trigger_release:
    - stages:
        - name: 发布到 $env
          script: echo "发布 $version 到 $env"

要点：

  • reg 是正则，控制按钮在哪些分支页面出现
  • inputs 支持八种类型：input、textarea、select、switch、radio、date、datetime、daterange
  • 用户填的值会变成环境变量（上面例子里是 $version、$env）
  • 目前只能在分支详情页配置按钮
  • .cnb/web_trigger.yml 不支持 include 和 imports

:::warning 日期默认值要加引号 default: "2026-08-01" 必须带引号，否则 YAML 会解析成 Date 对象。 :::

二、外部系统触发：api_trigger​

事件名格式：api_trigger 或以 api_trigger_ 开头。

三个触发入口本质是同一个：OpenAPI（POST /{repo}/-/build/start），cnb:apply 和 cnb:trigger 都是对它的封装。

curl --request POST \
  --url 'https://api.cnb.cool/<组织>/<仓库>/-/build/start' \
  --header 'Authorization: Bearer <你的令牌>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event": "api_trigger_deploy",
    "env": { "target": "prod" }
  }'

注意 api_trigger 默认归入可信事件，CNB_TOKEN 权限较宽。如果想收窄成 NPC 语义，可以传 npc 字段。

三、到点自己跑：定时任务​

.cnb.yml
main:
  "crontab: 30 5,17 * * *":
    - name: nightly-build-and-test
      stages:
        - name: run-tests
          script: echo "Running scheduled tasks..."

三个必须知道的规则：

  1. 分支名必须是明确的单一分支，不支持 glob
  2. 最小间隔 5 分钟，* * * * * 提交不上去
  3. 执行身份是最后修改这条 crontab 配置的人——那个人离职或被移出仓库，任务就失败

第 3 条特别容易踩。团队里最好约定：定时任务配置由常驻负责人改。

四、跨仓库联动：cnb:trigger 和 cnb:apply​

  • cnb:apply：触发当前仓库的另一条流水线
  • cnb:trigger：触发指定仓库的流水线，可同步等结果

典型场景：A 仓库改了公共库，需要触发 B、C 两个下游仓库重新构建。

.cnb.yml
$:
  push:
    - stages:
        - name: 触发下游
          type: cnb:trigger
          options:
            slug: my-group/downstream-repo
            event: api_trigger_build

多流水线之间要按顺序协作、传数据，用 cnb:await-resolve（cnb:await 等待 / cnb:resolve 通知）。

五、四类触发怎么选​

需求用什么
人点一下就走web_trigger + 页面按钮
系统自动调用api_trigger + OpenAPI
时间到了就跑crontab
仓库之间联动cnb:trigger / cnb:apply

六、触发之后想确认真跑了没​

云原生构建 → 历史事件。不过要注意：tag_deploy、web_deploy、API 事件、定时任务这些非代码事件不会出现在这里。它们要直接在构建列表里找。

另外重新构建产生的流水线也不在历史事件里。