Cloud Native Build supports configuring custom buttons to manually trigger pipelines from the web UI. Click a button to execute a web_trigger custom event. Environment variables can also be input on the page.

The effect is as follows:

Tips

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.

Tips

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:

.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:

.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:

.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 five input types: input, textarea, select, switch, radio.

.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 below for other input types.

Permission Control

Use permissions to restrict who can trigger builds:

.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:

.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:

.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:

.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):

.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 custom events.

  • isDefault: 选填，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. Note: Permissions can only be checked on the page.

    • users: Optional, Array<String>, username array. Multiple can be defined.
    • roles: Optional, Array<String>, repository role array. Multiple repository roles can be defined: owner, master(Administrator), developer, reporter, guest. Roles do not follow an upward inclusion hierarchy. For example, if only the master role is granted permissions, the owner—even with higher repository privileges—will not 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, or select.
    • required: Optional, Boolean, whether required
    • type: Optional, String, input type, can be input, textarea, select, switch, radio, default is input
    • default: Optional, String, default value
    • 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

    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 custom events. The corresponding pipeline must be configured in .cnb.yml.

.cnb.yml

release*:
  web_trigger_one:
    - stages:
        - name: Output Environment Variables
          script:
            - echo $a
            - echo $b
            - echo $var1
            - echo $var2
            - echo $var3

dev*:
  web_trigger_two:
    - stages:
        - name: Execute Task
          script: echo "job"

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

"**":
  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.

Previous pageLogin Debugging

Next pageCustom Deployment Process