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
    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: Create Approval Request
        # 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: Automated approval request process
        # Requires defining web_trigger_approval event pipeline in .cnb.yml
        event: web_trigger_approval
        # 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
        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_approval event pipeline
        # Can inherit from parent level env variables, with higher priority
        env:
          name1: value1
          name2: value2
        # 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
          var1:
            # Input box
            name: Variable 1
            description: Input Variable 1
            required: true # Whether required
            type: input
            default: Default Value 1
          var2:
            # Text area
            name: Variable 2
            description: Input Variable 2
            required: true
            type: textarea
            default: Default Value 2
          var3:
            # Single-select dropdown
            name: Variable 3
            description: Input 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: Input 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: Select Variable 5
            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: Radio Variable 6
            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, metadata, 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 Metadata 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 Metadata
            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: Metadata 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
            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
        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. 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.).

• 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.
    • 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. 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.).
  • 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, metadata 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.
    • 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:
      • description: Optional, String, description
      • 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
  1. Metadata requirement parameters:

  • annotation: Required. Metadata key.

  • expect: Optional. Requirements for metadata 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.

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 metadata when executed.

# .cnb.yml
$:
  # Events triggered by custom buttons
  web_trigger_annotation:
    - stages:
        - name: Upload Metadata
          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.