---
url: /en/build/web-trigger.md
description: >
  Explains how to configure custom buttons in CNB to manually trigger pipelines
  from the web UI, including the .cnb/web_trigger.yml configuration format and
  support for passing environment variables via the interface.
---
Cloud Native Build supports configuring custom buttons to manually trigger pipelines from the web UI.
Click a button to execute a [web\_trigger](./trigger-rule.md#web_trigger) custom event.
Environment variables can also be input on the page.

The effect is as follows:

![](/images/build/web-trigger-btn.en.png)

:::tip
Currently, custom buttons can only be configured on the `Code-Branch Details Page`.
:::

## Custom Button Configuration

Add a `.cnb/web_trigger.yml` file in the repository root directory to configure custom buttons.

:::tip

1. The `.cnb/web_trigger.yml` configuration file does not support `include` and `imports` syntax.
2. Custom button-triggered events need to be configured in the .cnb.yml file; otherwise,
   they cannot be triggered successfully.

:::

### Basic Example

The simplest configuration — only specify button name and event:

```yaml title=".cnb/web_trigger.yml"
branch:
  - buttons:
      - name: Button 4
        description: Button Description
        event: web_trigger_four
```

### Branch Matching

Use `reg` regex to control which branch pages display the button:

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^release
    buttons:
      - name: Release
        event: web_trigger_release

  - reg: ^dev
    buttons:
      - name: Dev Build
        event: web_trigger_dev

  - buttons:
      - name: Common Action
        event: web_trigger_common
```

### Environment Variables (env)

Use `env` to pass preset environment variables, supporting simple values and aliased format:

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^release
    buttons:
      - name: Release
        event: web_trigger_release
        env:
          a: 1
          b: 2
          c:
            name: Variable c
            value: 3
```

### Input Variables (inputs)

Use `inputs` to allow users to enter variables during execution, supporting eight input types:
`input`, `textarea`, `select`, `switch`, `radio`, `date`, `datetime`, `daterange`.

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^release
    buttons:
      - name: Release
        event: web_trigger_release
        inputs:
          var1:
            name: Version
            type: input
            required: true
            default: 1.0.0
          var2:
            name: Environment
            type: select
            default: staging
            options:
              - name: Dev
                value: dev
              - name: Staging
                value: staging
              - name: Production
                value: production
```

See the `inputs` field in the [Button type definition](#button-type-definition) below for other input types.

### Date Pickers (date / datetime / daterange)

`inputs` supports three date-picker types: `date` (date only), `datetime` (date + time), `daterange` (date range).

```yaml title=".cnb/web_trigger.yml"
branch:
  - buttons:
      - name: Scheduled Release
        event: web_trigger_scheduled_release
        inputs:
          release_date:
            name: Release Date
            description: Pick the planned release date; injected as an env var into the pipeline
            type: date
            required: true
            # Default value MUST be quoted, otherwise YAML will parse it as a Date object
            default: "2026-08-01"
            min: "2026-01-01"
            max: "2026-12-31"
          release_at:
            name: Release Time
            description: Release moment, precise to the minute
            type: datetime
            format: "YYYY-MM-DD HH:mm"
            default: "2026-08-01 10:00"
          range:
            name: Activity Range
            description: Start and end dates of the activity, used to define the rollout window
            type: daterange
            # daterange default value uses a comma to separate the start and end dates
            default: "2026-08-01,2026-08-31"
```

Environment variables received by the pipeline:

```text
release_date=2026-08-01
release_at=2026-08-01 10:00
range=2026-08-01,2026-08-31
```

::: tip

1. Default values must be quoted (e.g. `"2026-08-01"`); otherwise YAML will parse them as Date objects.
2. The default and submitted value of `daterange` use a comma to separate the start and end dates.
3. Dates are picked and displayed in the user's local time zone, and are passed to the pipeline as plain strings.

:::

### Permission Control

Use `permissions` to restrict who can trigger builds:

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^release
    buttons:
      - name: Release
        event: web_trigger_release
        permissions:
          roles:
            - master
            - developer
          users:
            - name1
            - name2
```

### Button Grouping

Use `groupName` to group buttons with dividers between groups:

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^feature
    buttons:
      - name: Build Project
        event: web_trigger_build
        groupName: Build Operations
      - name: Run Tests
        event: web_trigger_test
        groupName: Build Operations
      - name: Deploy Staging
        event: web_trigger_deploy
        groupName: Deploy Operations
```

### Inputs Grouping

Inputs also support grouping for scenarios with many parameters:

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^dev
    buttons:
      - name: Build
        event: web_trigger_dev
        inputs:
          - name: Basic Config
            collapsed: false
            inputs:
              var1:
                name: Version
                type: input
                required: true
              var2:
                name: Environment
                type: select
                options:
                  - name: Dev
                    value: dev
                  - name: Test
                    value: test
          - name: Advanced Config
            inputs:
              var3:
                name: Modules
                type: select
                multiple: true
                options:
                  - name: Module A
                    value: module-a
                  - name: Module B
                    value: module-b
              var4:
                name: Deploy Strategy
                type: radio
                options:
                  - name: Rolling
                    value: rolling
                  - name: Blue-Green
                    value: blue-green
```

### Other Features

**Default Button**: Set `isDefault: true` to make clicking the button directly open
the build dialog (only one takes effect).

**Launch Cloud Native Development**: Set `openWorkspace: true` to go directly to the launch page after triggering:

```yaml title=".cnb/web_trigger.yml"
branch:
  - buttons:
      - name: Launch Dev Environment
        event: web_trigger_launch_vscode
        openWorkspace: true
```

**Description Variable Substitution**: `description` supports referencing variables
from `env` and `inputs` (first-level only):

```yaml title=".cnb/web_trigger.yml"
branch:
  - buttons:
      - name: Button 6
        description: ${desc}
        event: web_trigger_six
        env:
          desc: Button Description
```

Currently, only custom buttons on the branch details page are supported. The key in yaml is `branch`,
and the value is in array format:

* `reg`: Optional, `String`,
  regular expression used to match branch names (only matched branches display custom buttons configured in `buttons`),
  if not filled, matches all branches
* `buttons`: Required, `Array<Button>`, custom button definition. `Button` type is defined as follows
  * `name`: Required, `String`, custom button name
  * `description`: Optional, `String`, button description. If exists, it will be used as the pipeline title,
    otherwise the pipeline will use the default title;
    Supports environment variable substitution (limited to first-level resolution only,
    applicable to currently configured env and inputs variables. Only the ${variable} notation format is supported.).
  * `image`: Optional, `String`, Custom button icon.
    Only images from the current branch of this repository can be used.
    Please provide the relative path to the repository root, such as .cnb/button.png.
  * `event`: Required, `String`, The name of the triggered CI event needs to be configured in the .cnb.yml file.
    only supports triggering [web\_trigger](./trigger-rule.md#web_trigger) custom events.
  * `isDefault`: Optional, `Boolean`. It is the default button, and only one
    default button is supported (if multiple are set, the first one is taken).
    If a default button is set, clicking the button will directly trigger
    the action of the default button and bring up the dialog box.
    If no default button is set, clicking the button will bring up
    a pop-up layer containing all custom buttons.
  * `groupName`: Optional, `String`, button group name.
    Buttons with the same `groupName` are displayed together as a group,
    with the group name shown as a title above the buttons, and dividers separating different groups.
    Buttons without a `groupName` configured are grouped together.
  * `openWorkspace`: Optional, `Boolean`, Is this to launch a cloud-native development environment? If yes,
    triggering the build will directly take you to the loading page for cloud-native development startup.
    If it is not for launching cloud development, do not configure this parameter.
  * `env`: Optional, `Object<String, String|EnvType>`,
    default environment variables passed to the web\_trigger custom event pipeline, not editable.
    Object key is the environment variable name;
    Object value supports two formats, `String` and `EnvType`. `EnvType` type is defined as follows:
    * `name`: Required, `String`, environment variable alias. Not the environment variable name passed to the pipeline
    * `value`: Required, `String`, environment variable value
  * `permissions`: Optional, permission control,
    satisfying either `users` or `roles` grants permission to trigger the build (repository write permission is also
    required). If `permissions` is not configured, repository write permission is sufficient to trigger the build.
    * `users`: Optional, `Array<String>`, username array. Multiple can be defined.
    * `roles`: Optional, `Array<String>`, repository role array.
      Only roles with repository write permission are supported:
      `owner`, `master`(Administrator), `developer`.
      Roles follow an upward inclusion hierarchy.
      For example, if only the master role is granted permissions,
      the owner—with higher repository privileges—will also have access in this context.
  * `inputs`: Optional, `Object<String, Input>`, manually input environment variables, object key is the variable name,
    `Input` type is defined as follows:

    * `name`: Required, `String`, the display name of the variable (not an environment variable key),
      used only for page display.
    * `description`: Optional, `String`, description
    * `placeholder`: Optional, `String`, Prompt information in the input box. Only valid when type is `input`,
      `textarea`, `select`, `date`, `datetime`, or `daterange`.
    * `required`: Optional, `Boolean`, whether required
    * `type`: Optional, `String`, input type, can be `input`, `textarea`, `select`, `switch`, `radio`,
      `date`, `datetime`, `daterange`, default is `input`
    * `default`: Optional, `String`, default value. For `date` / `datetime` provide a date string that matches
      `format` (e.g. `"2026-08-01"`, `"2026-08-01 10:00"`);
      for `daterange` use a comma-separated pair of dates (e.g. `"2026-08-01,2026-08-31"`).
      **Values must be quoted to prevent YAML from parsing them as Date objects.**
    * `multiple`: Optional, `Boolean`, whether to support multiple selection, only valid when type=`select`,
      multiple results are separated by semicolons. Commas should be avoided in the `value` of individual options
    * `options`: Optional, `Array<Option>`, options when `type: select` or `type: switch`.
      `Option` type is defined as follows:
      * `name`: Required, `String`, option name
      * `value`: Required, `String`, option value, used as environment variable value
      * `description`: Optional, `String`, option description
    * `format`: Optional, `String`, format template for date-family types (`date` / `datetime` / `daterange`).
      Defaults: `date` = `YYYY-MM-DD`, `datetime` = `YYYY-MM-DD HH:mm:ss`, `daterange` = `YYYY-MM-DD`.
    * `min`: Optional, `String`, earliest selectable date (inclusive) for date-family types.
      Date string, e.g. `"2026-01-01"`.
    * `max`: Optional, `String`, latest selectable date (inclusive) for date-family types.
      Date string, e.g. `"2026-12-31"`.

    `inputs` also supports grouping. It is defined as `Array<Object>`,
    where each array element is an object representing a group. The type definition is as follows:

    * `name`: Required, `String`. The group name (not an environment variable key),
      used only for display in the interface.
    * `collapsed`: Optional, `Boolean`. Whether to collapse this group by default,
      the default is `false` (do not collapse).
    * `inputs`: Required, `Object<String, Input>`. Defines the environment variables within the group.
      The object's keys are variable names,
      and the `input` type follows the same definition as the `Input` type described above.

## Custom web\_trigger Pipeline

The custom buttons in `.cnb/web_trigger.yml` only support triggering [web\_trigger](./trigger-rule.md#web_trigger)
custom events. The corresponding pipeline must be configured in `.cnb.yml`.

```yaml title=".cnb.yml"
release*:
  web_trigger_one:
    - stages:
        - name: Output Environment Variables
          script:
            - echo $a
            - echo $b
            - echo $var1
            - echo $var2
            - echo $var3
```

**web\_trigger events for `dev*` branches:**

```yaml title=".cnb.yml"
dev*:
  web_trigger_two:
    - stages:
        - name: Execute Task
          script: echo "job"

  web_trigger_three:
    - stages:
        - name: Execute Task
          script: echo "job"
```

**web\_trigger event for all branches:**

```yaml title=".cnb.yml"
"**":
  web_trigger_four:
    - stages:
        - name: Execute Task
          script: echo "job"
```

## Permission Description

Only users with `repository write permission` can click custom buttons to execute `web_trigger` pipelines.
If a button configures `permissions`, the user must also be listed in its `users` / `roles`.