手动触发流水线
手动触发流水线 介绍如何在页面上配置自定义按钮来手动触发流水线。
使用场景：不想每次手动拼接参数时才触发构建时使用——例如发版按钮、按环境一键部署， 或让不熟悉命令行的同学也能在页面上点按钮执行。点击按钮即执行 web_trigger 自定义事件，同时支持在页面上输入环境变量。
效果如下：
提示
目前仅支持在「代码-分支详情页」上配置自定义按钮。
自定义按钮配置
在仓库根目录下创建 .cnb/web_trigger.yml 文件来配置自定义按钮。
提示
.cnb/web_trigger.yml不支持include和imports语法。- 自定义按钮触发的事件需在
.cnb.yml中配置，否则无法触发。
基础示例
最简配置——仅指定按钮名和事件名：
branch:
- buttons:
- name: 按钮名4
description: 按钮描述
event: web_trigger_four分支匹配
通过 reg 正则表达式控制按钮在哪些分支详情页显示：
branch:
- reg: ^release
buttons:
- name: 发布
event: web_trigger_release
- reg: ^dev
buttons:
- name: 开发构建
event: web_trigger_dev
- buttons:
- name: 通用操作
event: web_trigger_common环境变量（env）
通过 env 传入预置环境变量，支持简单值和带别名的格式：
branch:
- reg: ^release
buttons:
- name: 发布
event: web_trigger_release
env:
a: 1
b: 2
c:
name: 变量c
value: 3可输入环境变量（inputs）
通过 inputs 允许用户在执行时手动输入变量，支持八种输入类型：input、textarea、 select、switch、radio、date、datetime、daterange。
branch:
- reg: ^release
buttons:
- name: 发布
event: web_trigger_release
inputs:
var1:
name: 版本号
type: input
required: true
default: 1.0.0
var2:
name: 环境
type: select
default: staging
options:
- name: 开发环境
value: dev
- name: 预发布
value: staging
- name: 生产环境
value: production其他输入类型详见下方 Button 类型定义 中的 inputs 字段。
日期选择器（date / datetime / daterange）
inputs 支持三种日期选择器类型：date（日期）、datetime（日期时间）、daterange（日期范围）。
branch:
- buttons:
- name: 定时发布
event: web_trigger_scheduled_release
inputs:
release_date:
name: 发布日期
description: 选择计划发布的日期，将作为环境变量注入流水线
type: date
required: true
# 默认值必须加引号，避免被 YAML 解析为 Date 对象
default: "2026-08-01"
min: "2026-01-01"
max: "2026-12-31"
release_at:
name: 发布时刻
description: 精确到分钟的发布时间
type: datetime
format: "YYYY-MM-DD HH:mm"
default: "2026-08-01 10:00"
range:
name: 活动区间
description: 活动的起止日期，用于生成灰度窗口
type: daterange
# daterange 默认值用逗号分隔起止日期
default: "2026-08-01,2026-08-31"传给流水线的环境变量：
release_date=2026-08-01
release_at=2026-08-01 10:00
range=2026-08-01,2026-08-31提示
- 默认值必须用引号包裹（如
"2026-08-01"），否则会被 YAML 解析为 Date 对象。 daterange的默认值和最终传值都用英文逗号分隔起止日期。- 日期按用户浏览器本地时区显示与选择，最终以字符串形式作为环境变量注入流水线。
权限控制
通过 permissions 限制可触发构建的用户或角色：
branch:
- reg: ^release
buttons:
- name: 发布
event: web_trigger_release
permissions:
roles:
- master
- developer
users:
- name1
- name2按钮分组
通过 groupName 将按钮分组显示，不同分组间有分割线：
branch:
- reg: ^feature
buttons:
- name: 构建项目
event: web_trigger_build
groupName: 构建操作
- name: 运行测试
event: web_trigger_test
groupName: 构建操作
- name: 部署预发布
event: web_trigger_deploy
groupName: 部署操作inputs 分组
inputs 也支持分组，适用于参数较多的场景：
branch:
- reg: ^dev
buttons:
- name: 构建
event: web_trigger_dev
inputs:
- name: 基础配置
collapsed: false
inputs:
var1:
name: 版本号
type: input
required: true
var2:
name: 环境
type: select
options:
- name: 开发
value: dev
- name: 测试
value: test
- name: 高级配置
inputs:
var3:
name: 模块
type: select
multiple: true
options:
- name: 模块A
value: module-a
- name: 模块B
value: module-b
var4:
name: 部署策略
type: radio
options:
- name: 滚动更新
value: rolling
- name: 蓝绿部署
value: blue-green其他特性
默认按钮：设置 isDefault: true 后点击按钮直接弹出该按钮的构建弹框（仅一个生效）。
启动云原生开发：设置 openWorkspace: true，触发构建后直接进入云原生开发启动页：
branch:
- buttons:
- name: 启动开发环境
event: web_trigger_launch_vscode
openWorkspace: truedescription 变量替换：description 支持引用 env 和 inputs 中的变量（仅支持替换一级）：
branch:
- buttons:
- name: 按钮6
description: ${desc}
event: web_trigger_six
env:
desc: 按钮描述目前仅支持配置分支详情页的自定义按钮。YAML 中键名为 branch，值为数组格式：
reg：选填，String，正则表达式，用于匹配分支名 （仅匹配到的分支显示buttons配置的自定义按钮）。未填则匹配全部分支。buttons：必填，Array<Button>，自定义按钮定义。Button类型定义如下：name：必填，String，自定义按钮名description：选填，String，按钮描述。如存在，将作为流水线 title，否则使用默认 title； 支持环境变量替换（仅支持替换一级，环境变量指当前配置的 env 和 inputs，仅支持 ${xxx} 写法）image：选填，String，自定义按钮图标。只能用本仓库中当前分支的图片，填写相对仓库根目录的路径，如 .cnb/button.pngevent：必填，String，触发的 CI 事件名，需要在.cnb.yml中配置。 仅支持 web_trigger 自定义事件。isDefault：选填，Boolean，是否为默认按钮，仅支持设置一个 （设置多个时取第一个）。设置默认按钮后，点击按钮直接弹出默认按钮的 触发构建弹框；未设置时，点击按钮弹出包含所有自定义按钮的弹层。groupName：选填，String，按钮分组名。 相同groupName的按钮会分组显示在一起，分组名会作为标题显示在按钮上方， 不同分组之间有分割线隔开。未配置groupName的按钮归为同一组。openWorkspace：选填，Boolean，是否启动云原生开发环境。 开启后触发构建将直接进入云原生开发的启动页。 非云开发场景请勿配置此参数。env：选填，Object<String, String|EnvType>，传给 web_trigger 自定义事件流水线的默认环境变量，不支持编辑。 对象键值为环境变量名； 对象值支持两种格式，String和EnvType。EnvType类型定义如下：name：必填，String，环境变量别名。非传给流水线的环境变量名value：必填，String，环境变量值
permissions：选填，权限控制，满足users或roles之一即可触发构建 （还需仓库写权限）。未配置时，有仓库写权限即可触发。users：选填，Array<String>，用户名数组。可定义多个。roles：选填，Array<String>，仓库角色数组。仅支持具备仓库写权限的角色：owner（负责人）、master（管理员）、developer（开发者）。 角色为向上包含，例如仅声明master有权限，owner仓库权限更高，同样也有权限。
inputs：选填，Object<String, Input>，可手动输入的环境变量，对象的键值为变量名，Input类型定义如下：name：必填，String，输入选项名称，非环境变量键值，仅用于页面展示description：选填，String，描述信息placeholder：选填，String，输入框内提示信息。仅当 type=input、textarea、select、date、datetime、daterange时有效required：选填，Boolean，是否必填type：选填，String，输入框类型，可选input、textarea、select、switch、radio、date、datetime、daterange，默认为inputdefault：选填，String，默认值。date/datetime填写符合format的日期字符串（如"2026-08-01"、"2026-08-01 10:00"），daterange使用英文逗号分隔的起止日期（如"2026-08-01,2026-08-31"）， 均需加引号避免被 YAML 解析为 Date 对象multiple：选填，Boolean，是否支持多选，仅当 type=select时有效， 多选结果用分号分隔。单个选项的value中需避免出现逗号options：选填，Array<Option>，当type: select或type: switch时的选项。Option类型定义如下：name：必填，String，选项名value：必填，String，选项值，作为环境变量值description：选填，String，选项描述信息
format：选填，String，日期系类型（date/datetime/daterange）的格式化模板。 默认：date为YYYY-MM-DD，datetime为YYYY-MM-DD HH:mm:ss，daterange为YYYY-MM-DDmin：选填，String，日期系类型允许选择的最早日期（含边界，日期字符串如"2026-01-01"）max：选填，String，日期系类型允许选择的最晚日期（含边界，日期字符串如"2026-12-31"）
inputs也支持分组，Array<Object>，每个数组元素是一个对象，表示一个分组，类型定义如下：name：必填，String，分组名称，非环境变量键值，仅用于页面展示collapsed：非必填，Boolean，是否默认折叠该分组，默认为false不折叠inputs：必填，Object<String, Input>，分组内环境变量定义， 对象的键值为变量名，Input类型定义同上方Input类型定义。
自定义 web_trigger 流水线
.cnb/web_trigger.yml 中的自定义按钮仅支持触发 web_trigger 自定义事件， 需在 .cnb.yml 中配置对应的流水线。
release*:
web_trigger_one:
- stages:
- name: 输出环境变量
script:
- echo $a
- echo $b
- echo $var1
- echo $var2
- echo $var3dev* 分支的 web_trigger 事件：
dev*:
web_trigger_two:
- stages:
- name: 执行任务
script: echo "job"
web_trigger_three:
- stages:
- name: 执行任务
script: echo "job"所有分支的 web_trigger 事件：
"**":
web_trigger_four:
- stages:
- name: 执行任务
script: echo "job"权限说明
仅有仓库写权限的用户可点击自定义按钮执行 web_trigger 流水线。 若按钮配置了 permissions，还需是其中列出的 users / roles 才能触发。