Cloud Native Build supports custom deployment processes through custom deployment environments, approval workflows, and deployment pipelines to achieve automated deployment.

Example operation:

Custom Deployment Environments

Add a .cnb/tag_deploy.yml file in the repository root directory to configure deployment environments. The example below defines three environments: development, staging, and production. Users can select the desired environment type on the page.

.cnb/tag_deploy.yml

environments:
  # name: Environment name, clicking the deploy button for this environment will trigger the tag_deploy.development event pipeline in .cnb.yml
  - name: development
    description: Development environment
    # Deploy Button Permission Control
    # Not configured: Users with repository write permission and tag_push permission can click the deploy button
    # Configured: Users must have repository write permission and meet one of the roles or users conditions to have permission to click the deploy button
    permissions:
      # One or both of roles and users can be configured; meeting either condition is sufficient
      # Roles are not upwardly inclusive. For example, with the following configuration, only the master or developer roles have permission. Even if an owner has higher repository permissions, they will not have permission here.
      roles:
        - master
        - developer
      users:
        - name1
        - name2
    # Environment variables (passed to the pipeline when triggered, including deployment pipelines and web_trigger pipelines)
    env:
      name: development
      # CNB_BRANCH: Environment variable, in deployment events it's the tag name
      tag_name: $CNB_BRANCH

  - name: staging
    description: Staging environment
    # Custom-triggered deployment pipeline title
    # title: 部署预发布环境
    env:
      name: staging
      # CNB_BRANCH: Environment variable, in deployment events it's the tag name
      tag_name: $CNB_BRANCH

  - name: production
    description: Production environment
    # Environment variables (passed to the pipeline when triggered, including deployment pipelines and web_trigger pipelines)
    env:
      name: production
      # CNB_BRANCH: Environment variable, in deployment events it's the tag name
      tag_name: $CNB_BRANCH
    button:
      - 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
      - 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

    # Pre-deployment condition checks (supports environment, annotation, and approval workflow checks)
    # All conditions must be met before deployment can proceed
    require:
      # 1 Environment requirement checks

      # 1.1 Requires successful deployment of development environment
      - environmentName: development

      # 1.2 Requires staging environment deployed successfully 30 minutes ago
      - environmentName: staging
        after: 1800

      # 2 Annotation requirement checks

      # 2.1 Key key1 must have a non-empty value
      - annotation: key1

      # 2.2 Key key1 value must equal value1
      - annotation: key1
        expect:
          eq: value1

      # 2.3 Key key2 value must be greater than 1 and less than 10
      - annotation: key2
        expect:
          and:
            gt: 1
            lt: 10
        # Custom button that triggers web_trigger_annotation event when clicked
        # Can define button events related to require conditions (button hides when conditions are met)
        button:
          - name: Generate Annotation
            event: web_trigger_annotation
            # If exists, will be used as pipeline title, otherwise default title is used; 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: Annotation generation process
            # Permission control - if not configured, users with repository write permission can trigger builds
            # If configured, requires repository write permission AND meeting either roles or users conditions
            # Note: Permissions can only be checked on the page.
            permissions:
              # Can configure either roles or users or both - meeting either 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 passed to web_trigger_annotation pipeline
            # Can inherit from parent level env variables, with higher priority
            env:
              name1: value1
              name2: value2

      # 3 Approval workflow requirement checks (can customize approval workflow as below)
      # - Approval sequence: Steps 1,2,3 must proceed in order (1 must be approved before 2 can proceed)
      # - Approval actions: Include approve/reject. One approval is sufficient. If rejected, others cannot act until rejection is changed to approval

      # 3.1 Approvers by username - one approval is sufficient
      - approver:
          users:
            - user1
            - user2
            - user3
        # 可配置点击同意按钮触发的事件，以及传给事件流水线的环境变量
        # agreeEvent:
        #   # 描述信息，会作为流水线 title
        #   description: 同意审批
        #   # 点击同意按钮时触发的事件名，仅支持 web_trigger 事件
        #   event: web_trigger_agree
        #   # 传给事件流水线的环境变量，不支持继承上一级别的环境变量
        #   env:
        #     name1: value1
        #     name2: value2
        # 可配置点击拒绝按钮触发的事件，以及传给事件流水线的环境变量
        # rejectEvent:
        #   # 描述信息，会作为流水线 title
        #   description: 拒绝审批
        #   # 点击拒绝按钮时触发的事件名，仅支持 web_trigger 事件
        #   event: web_trigger_reject
        #   # 传给事件流水线的环境变量，不支持继承上一级别的环境变量
        #   env:
        #     name1: value1
        #     name2: value2
        title: Test Approval

      # 3.2 Approvers by role - one approval is sufficient
      - approver:
          roles:
            - developer
            - master
        title: Development Approval

      # 3.3 Approvers by username OR role (meeting either users or roles condition) - one approval is sufficient
      - approver:
          users:
            - user4
            - user5
          roles:
            - master
            - owner
        title: Operations Approval

    # Custom deploy buttons (default: shows one deploy button)
    # Use case: When multiple modules (e.g. repository, CI, artifacts) need separate deployments
    # Note: In deployment pipeline, distinguish modules using environment variables
    deploy:
      - name: Deploy Button 1
        description: Deploy button description
        # Environment variables (passed to deployment pipeline), higher priority than parent env
        env:
          name1: value1
          name2: value2
      - name: Deploy Button 2
        description: Deploy button description
        # Environment variables (passed to deployment pipeline), higher priority than parent env
        env:
          name1: value1
          name2: value2

• name: Required, environment name, must be unique. Example: name: development - clicking deploy button for this environment triggers tag_deploy.development event pipeline in .cnb.yml

• description: Optional, button description.

• title: Optional, Custom-triggered deployment pipeline title

• env: Optional, environment variables passed to deployment pipeline

• permissions: Optional. Deployment permission control. Users who meet either the usersor rolescondition will have deployment permission (in addition to having repository write permission). If permissionsis not configured, users with repository write permission and tag push permission can trigger the build.

  • users: Optional. Array<String>. Array of usernames. Multiple usernames can be defined.
  • roles: Optional. Array<String>. Array of repository roles. Multiple repository roles can be defined: owner(Owner), master(Administrator), developer(Developer), reporter(Reporter), guest(Guest). Roles are not upwardly inclusive. For example, if only masteris declared to have permission, even though ownerhas higher repository permissions, they will not have permission here.

• button: Optional, array of objects, custom buttons. Clicking button triggers Cloud Native Build pipeline for specified event.

  • name: Required, button name.
  • description: Optional, button description. If exists, used as pipeline title, otherwise 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.).
  • event: Required, custom event, only supports web_trigger events.
  • env: Optional, environment variables passed to web_trigger pipeline, can inherit from parent env with higher priority.
  • permissions: Optional, permission control - requires repository write permission AND meeting either users or roles conditions. If not configured, only repository write permission is needed. Note: Permissions can only be checked on the page.
    • users: Optional, Array<String>, username array.
    • roles: Optional, Array<String>, repository role array: owner、master(i.e., 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.

• deploy: Optional, array of objects, custom deploy buttons. Clicking button triggers deployment event (tag_deploy.*).

  • name: Required, button name.
  • description: Optional, button description.
  • title: Optional, Custom-triggered deployment pipeline title. Priority is higher than the previous level's title.
  • env: Optional, environment variables passed to deployment pipeline, higher priority than parent env.

• require: Optional, array of objects. Pre-deployment conditions that must all be met (environment requirements, annotation requirements, approval workflows).

  1. Environment requirement parameters:

  • environmentName: Required. Environment name.

  • after: Optional. Time in seconds. Indicates environmentName must have been deployed successfully for this duration.

  • description: Optional. Description of require condition.

  • button: Optional. Custom button that triggers specified event when clicked. Button hides when condition is met.

    • name: Required, button name.

    • event: Required, custom event, only supports web_trigger_* 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.

    • description: Optional, button description. If exists, used as pipeline title.

    • env: Optional, environment variables passed to web_trigger pipeline.

    • permissions: Optional, permission control - requires repository write permission AND meeting either users or roles conditions. If not configured, only repository write permission is needed.

      • users: Optional, Array<String>, username array.
      • roles: Optional, Array<String>, repository role array: owner、master(i.e., 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, 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.
  1. Annotation requirement parameters:

  • annotation: Required. Annotation key.

  • expect: Optional. Requirements for annotation value. Object format supporting eq, ne, gt, lt, gte, lte, and, or, reg operators.

    • eq: Equal to
    • ne: Not equal to
    • gt: Greater than
    • lt: Less than
    • gte: Greater than or equal to
    • lte: Less than or equal to
    • and: AND
    • or: OR
    • reg: Match a regular expression

  • description: Optional. Description of require condition.

  • button: Optional. Custom button that triggers event when clicked. Button hides when condition is met.

    • name: Required, button name.
    • event: Required, custom event, only supports web_trigger_* events.
    • description: Optional, button description. If exists, used as pipeline title.
    • env: Optional, environment variables passed to web_trigger pipeline.
    • permissions: Optional, permission control - requires repository write permission AND meeting either users or roles conditions. If not configured, only repository write permission is needed.
      • users: Optional, Array<String>, username array.
      • roles: Optional, Array<String>, repository role array: owner、master(i.e., 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.
  1. Approval workflow parameters:
  • approver: Required, approver definition - one approval from specified users or roles is sufficient.
    • users: Username array.
    • roles: Repository role array. owner、master(i.e., Administrator)、developer、reporter、guest
  • title: Optional, approval title like Test Approval.
  • agreeEvent: Optional, the event triggered after successfully clicking the agree approval button
    • description: Optional, description information, will be used as the pipeline title.
    • event: Required, event name, only the web_trigger event is supported.
    • env: Optional, environment variables passed to the pipeline. Environment variables from the parent level are not inherited.
  • rejectEvent: Optional, the event triggered after successfully clicking the reject approval button
    • description: Optional, description information, will be used as the pipeline title.
    • event: Required, event name, only the web_trigger event is supported.
    • env: Optional, environment variables passed to the pipeline. Environment variables from the parent level are not inherited.

Custom Deployment Preconditions

Preconditions can be defined for each environment, and deployment can only proceed if all preconditions are met. The following three types of preconditions can be defined:

• Environment Deployment Requirement: Requires that a specified environment has been deployed successfully and meets the after time requirement.
• Annotation Value Requirement: Requires that the value of a specified annotation key meets certain conditions.
• Approval Process Requirement: Allows custom approval processes with designated approvers. Only when all approval steps are approved is the requirement considered satisfied.

Example: Environment Deployment Preconditions

.cnb/tag_deploy.yml

environments:
  - name: development
    description: Development environment
    env:
      name: development
      tag_name: $CNB_BRANCH

  - name: staging
    description: Staging environment
    env:
      name: staging
      tag_name: $CNB_BRANCH
    require:
      # Requires successful deployment of the development environment
      - environmentName: development

  - name: production
    description: Production environment
    require:
      # Requires successful deployment of the staging environment 30 minutes ago
      - environmentName: staging
        after: 1800

Example: Annotation Preconditions

.cnb/tag_deploy.yml

environments:
  - name: production
    description: Production environment
    require:
      # Checks for annotation value requirements

      # The value for key1 must not be empty (i.e., it must have a value)
      - annotation: key1

      # The value for key2 must equal value1
      - annotation: key2
        expect:
          eq: value2

      # The value for key3 must be greater than 1 and less than 10
      - annotation: key3
        expect:
          and:
            gt: 1
            lt: 10
        # Custom button; clicking it triggers the web_trigger_annotation event.
        # Buttons related to the requirement can be defined. The button is hidden once the requirement is satisfied.
        button:
          - name: Generate Annotation
            event: web_trigger_annotation
            # If provided, this will be used as the pipeline title; otherwise, the default title is used.
            # Supports environment variable substitution (only first-level substitution; env and inputs from the current configuration. Only supports ${xxx} syntax.)
            description: Generate Annotation Workflow
            # Environment variables passed to the web_trigger_annotation event pipeline
            # Inherits higher-level environment variables; higher priority than higher-level variables
            env:
              name1: value1
              name2: value2

Example: Approval Process Preconditions

Custom approval processes and designated approvers can be defined. Authorized approvers can perform approval actions (approve or reject). The requirement is considered satisfied only when all approval steps are approved.

.cnb/tag_deploy.yml

environments:
  - name: production
    description: Production environment
    require:
      # Checks for approval process requirements (custom approval processes can be defined as follows)
      # - Approval sequence: Steps 1, 2, and 3 must be performed in order. Step 2 can only proceed after step 1 is approved.
      #   All three steps must be approved for the overall approval to pass.
      # - Approval actions: Include "approve" and "reject." Approval by one person is sufficient. If rejected, other approvers cannot act until the rejecting approver changes their decision to approve.

      # Approve by usernames; approval by any one of them is sufficient
      - approver:
          users:
            - user1
            - user2
            - user3
        # Events triggered by clicking the "Approve" button and environment variables passed to the event pipeline can be configured
        # agreeEvent:
        #   # Description, used as the pipeline title
        #   description: Approve Request
        #   # Event triggered when the "Approve" button is clicked; only supports web_trigger events
        #   event: web_trigger_agree
        #   # Environment variables passed to the event pipeline; does not inherit higher-level environment variables
        #   env:
        #     name1: value1
        #     name2: value2
        # Events triggered by clicking the "Reject" button and environment variables passed to the event pipeline can be configured
        # rejectEvent:
        #   # Description, used as the pipeline title
        #   description: Reject Request
        #   # Event triggered when the "Reject" button is clicked; only supports web_trigger events
        #   event: web_trigger_reject
        #   # Environment variables passed to the event pipeline; does not inherit higher-level environment variables
        #   env:
        #     name1: value1
        #     name2: value2
        title: Test Approval

      # Approve by roles; approval by any one of the roles is sufficient
      - approver:
          roles:
            - developer
            - master
        title: Developer Approval

      # Approve by usernames or roles (approvers must satisfy either users or roles); approval by any one of them is sufficient
      - approver:
          users:
            - user4
            - user5
          roles:
            - master
            - owner
        title: Operations Approval

Custom Deployment Pipelines

The example below defines deployment pipelines for three environments. When selecting development environment on the page, it triggers the tag_deploy.development event. The pipeline performs deployment operations based on the code corresponding to the current tag.

.cnb.yml

$:
  tag_deploy.development:
    - name: dev
      stages:
        - name: Environment name
          script: echo $name
        - name: Tag name
          script: echo $tag_name
  tag_deploy.staging:
    - name: staging
      stages:
        - name: Environment name
          script: echo $name
        - name: Tag name
          script: echo $tag_name
  tag_deploy.production:
    - name: production
      stages:
        - name: Environment name
          script: echo $name
        - name: Tag name
          script: echo $tag_name

The relationship between pipeline event names and environment types is:

• tag_deploy.development: development
• tag_deploy.staging: staging
• tag_deploy.production: production

Custom Button Web_trigger Events

Custom buttons in tag_deploy.yml can only trigger web_trigger events. In the pipeline configuration below, the web_trigger_annotation event uploads Annotation when executed.

.cnb.yml

$:
  # Events triggered by custom buttons
  web_trigger_annotation:
    - stages:
        - name: Upload Annotation
          image: cnbcool/annotations:latest
          settings:
            data: |
              key1=value1
              key2=value2

Deployment Permissions

Users need repository write permission AND tag push permission to perform deployment operations.

If the permissions field is configured, users with repository write permission and meeting the permissions defined in the permissions field can perform deployment operations. At this time, the tag push permission is not checked.