Cloud Native Build supports configuring custom buttons on the page to trigger pipeline execution by clicking (only supports triggering web_trigger custom events). It also supports inputting environment variables 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. Note that the .cnb/web_trigger.yml configuration file does not support include and imports syntax.

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.

# .cnb/web_trigger.yml
branch:
  # The following buttons are displayed on the branch details page where the branch name starts with release
  - reg: "^release"
    buttons:
      - name: Button Name 1
        # 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.).
        description: Button Description
        # The name of the triggered CI event needs to be configured in the .cnb.yml file.
        event: web_trigger_one
        # Whether the button is the default button
        isDefault: false
        # Permission control, if not configured, users with repository write permission can trigger the build
        # If configured, repository write permission is required, and either roles or users must be satisfied to have permission to trigger the build
        # Note: Permissions can only be checked on the page.
        permissions:
          # Configure either roles or users or both, satisfying either one is sufficient
          # The roles do not have an upward inclusion relationship. For example, in the following configuration, only users with the "master" or "developer" roles have permissions. Even if the "owner" has higher repository permissions, they are not granted access here.
          roles:
            - master
            - developer
          users:
            - name1
            - name2
        # Environment variables
        env:
          # Default environment variables, where key values (a,b,c) are environment variable names, supporting the following two formats
          a: 1
          b: 2
          c:
            # Environment variable alias
            name: Variable c
            # Environment variable value
            value: 3
        # Input environment variables, can override the above env variable configuration
        inputs:
          # Currently supports three formats: input box (input), multi-line text input box (textarea), dropdown selection box (select supports single and multiple selection), switch(switch), radio box (radio)
          # Where key values (var1, var2, var3, var4, var5, var6) are environment variable names
          # inputs also support grouping environment variables. See the configuration of Button 2's inputsbelow.
          var1:
            # Input box
            name: Variable 1
            description: Variable 1 Description
            placeholder: Place input variable 1
            required: true # Whether required
            type: input
            default: Default Value 1
          var2:
            # Text area
            name: Variable 2
            description: Variable 2 Description
            placeholder: Place input variable 2
            required: true
            type: textarea
            default: Default Value 2
          var3:
            # Single-select dropdown
            name: Variable 3
            description: Variable 3 Description
            placeholder: Place select variable 3
            required: false
            type: select
            default: value1
            options:
              - name: Option 1
                value: value1
                description: Option 1 Description
              - name: Option 2
                value: value2
                description: Option 2 Description
          var4:
            # Multi-select dropdown
            name: Variable 4
            description: Variable 4 Description
            placeholder: Place select variable 4
            required: false
            type: select
            # Whether to support multiple selection, multiple results are separated by semicolons
            multiple: true
            default: value1,value2
            options:
              - name: Option 1
                value: value1
                description: Option 1 Description
              - name: Option 2
                value: value2
                description: Option 2 Description
              - name: Option 3
                value: value3
                description: Option 3 Description
          var5:
            # Switch
            name: Variable 5
            description: Variable 5 Description
            required: false
            type: switch
            default: value1
            options:
              - name: Option 1
                value: value1
                description: Option 1 Description
              - name: Option 2
                value: value2
                description: Option 2 Description
          var6:
            # Radio
            name: Variable 6
            description: Variable 6 Description
            required: false
            type: radio
            default: value1
            options:
              - name: Option 1
                value: value1
                description: Option 1 Description
              - name: Option 2
                value: value2
                description: Option 2 Description

  # The following buttons are displayed on the branch details page where the branch name starts with dev
  - reg: "^dev"
    buttons:
      - name: Button Name 2
        description: Button Description
        event: web_trigger_two
        # Input environment variables, can override the above env variable configuration
        inputs:
          # inputs support grouping, as shown below. Use an array format where each array element represents a group.
          # Grouping is only for display purposes in the interface and does not affect the actual environment variables passed in.
          - name: Group 1
            inputs:
              # Currently supports three formats: input box (input), multi-line text input box (textarea), dropdown selection box (select supports single and multiple selection), switch(switch), radio box (radio)
              # Where key values (var1, var2, var3, var4, var5, var6) are environment variable names
              var1:
                # Input box
                name: Variable 1
                description: Variable 1 Description
                placeholder: Place input variable 1
                required: true # Whether required
                type: input
                default: Default Value 1
              var2:
                # Text area
                name: Variable 2
                description: Variable 2 Description
                placeholder: Place input variable 2
                required: true
                type: textarea
                default: Default Value 2
              var3:
                # Single-select dropdown
                name: Variable 3
                description: Variable 3 Description
                placeholder: Place select variable 3
                required: false
                type: select
                default: value1
                options:
                  - name: Option 1
                    value: value1
                    description: Option 1 Description
                  - name: Option 2
                    value: value2
                    description: Option 2 Description
          - name: Group 2
            inputs:
              var4:
                # Multi-select dropdown
                name: Variable 4
                description: Variable 4 Description
                placeholder: Place select variable 4
                required: false
                type: select
                # Whether to support multiple selection, multiple results are separated by semicolons
                multiple: true
                default: value1,value2
                options:
                  - name: Option 1
                    value: value1
                    description: Option 1 Description
                  - name: Option 2
                    value: value2
                    description: Option 2 Description
                  - name: Option 3
                    value: value3
                    description: Option 3 Description
              var5:
                # Switch
                name: Variable 5
                description: Variable 5 Description
                required: false
                type: switch
                default: value1
                options:
                  - name: Option 1
                    value: value1
                    description: Option 1 Description
                  - name: Option 2
                    value: value2
                    description: Option 2 Description
          - name: Group 3
            inputs:
              var6:
                # Radio
                name: Variable 6
                description: Variable 6 Description
                required: false
                type: radio
                default: value1
                options:
                  - name: Option 1
                    value: value1
                    description: Option 1 Description
                  - name: Option 2
                    value: value2
                    description: Option 2 Description
      - name: Button Name 3
        description: Button Description
        event: web_trigger_three

  # The following custom buttons are displayed on all branch details pages
  - buttons:
      - name: Button Name 4
        description: Button Description
        event: web_trigger_four
      - name: Button Name 5
        description: Button Description
        event: web_trigger_launch_vscode
        # Is it to launch a cloud-native development environment? If yes, after triggering the build, it will directly enter the loading page for the cloud-native development startup
        openWorkspace: true
      - name: Button Name 6
        # This references a first-level environment variable. The pipeline title displays as: Button Description.
        description: ${description}
        event: web_trigger_six
        env:
          description: Button Description
      - name: Button Name 7
        # This involves a second-level environment variable reference, with only first-level substitution performed. The pipeline title resolves to: ${title}.
        description: ${description}
        event: web_trigger_seven
        env:
          description: ${title}
          title: 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. The array elements are defined as follows:

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

  • 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 masterrole 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.
    • 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 web_trigger event pipeline is configured in .cnb.yml

# .cnb.yml

# Match branch names starting with release
release*:
  # Events that can be triggered by custom buttons
  web_trigger_one:
    - stages:
        - name: Output Environment Variables
          script:
            - echo $a
            - echo $b
            - echo $var1
            - echo $var2
            - echo $var3

# Match branch names starting with dev
dev*:
  web_trigger_two:
    - stages:
        - name: Execute Task
          script: echo "job"

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

# Match all branch names
"**":
  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.