Cloud Native Build supports custom deployment workflows with configurable deployment environments, approval processes, and deployment pipelines for automated releases.

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.

Basic Example

Simplest configuration, defining three deployment environments:

.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
  - name: production
    description: Production environment
    env:
      name: production
      tag_name: $CNB_BRANCH

Permission Control

Use permissions to restrict deployment execution:

.cnb/tag_deploy.yml

environments:
  - name: production
    description: Production environment
    permissions:
      roles:
        - master
        - developer
      users:
        - name1
        - name2

Custom Buttons (button)

Add button in environment config to trigger custom web_trigger events:

.cnb/tag_deploy.yml

environments:
  - name: production
    description: Production environment
    button:
      - name: Generate Release Notes
        description: Auto-generate Release Notes
        event: web_trigger_release_notes
        env:
          a: 1
          b: 2

Custom Deploy Buttons (deploy)

In multi-module scenarios, use deploy to configure multiple deploy buttons, distinguished by env:

.cnb/tag_deploy.yml

environments:
  - name: production
    description: Production environment
    deploy:
      - name: Deploy Frontend
        env:
          module: frontend
      - name: Deploy Backend
        env:
          module: backend

deploy button env vars can only be pre-configured via env, not entered by users on the page. Deployment is a serious operation; related parameters should be version-controlled.

Field Reference

• name: Required, environment name, must be unique (e.g. name: development). Clicking the corresponding deploy button triggers the tag_deploy.development event in .cnb.yml.

• description: Optional, environment 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 users or roles condition will have deployment permission (in addition to having repository write permission). If permissions is 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. Only roles with repository write permission are supported: owner, master, developer. Roles are upwardly inclusive: for example, if only master is granted, owner (which has higher repository permissions) is also granted.

• 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.
  • event: Required, custom event, only supports web_trigger events.
  • isDefault: Optional, Boolean. Only one default button is supported.
  • env: Optional, environment variables passed to web_trigger pipeline.
  • permissions: Optional, permission control. Meeting either users or roles (deployment permission of the environment is also required).
  • inputs: Optional, manually input environment variables, supporting input, textarea, select, switch, radio types, also supporting grouping. See Web Trigger - Custom Button Configuration for details.

• deploy: Optional, array of objects, custom deploy buttons for deployment events (tag_deploy.*).

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

• require: Optional, array of objects. Pre-deployment conditions must all be met. Supports three types:

  • Environment Requirement
    • environmentName: Required, String, the name of the environment this depends on; requires that environment to have been deployed successfully
    • after: Optional, Number, seconds to wait after the dependent environment has been deployed
    • button: Optional, custom button. Shown when the condition is not met; clicking it triggers a web_trigger event to satisfy the condition
  • Annotation Requirement
    • annotation: Required, String, annotation key; requires the value to be non-empty
    • expect: Optional, condition the annotation value must satisfy, supports eq/ne/gt/lt/gte/lte/and/or/reg
    • button: Optional, custom button. Shown when the condition is not met; clicking it triggers a web_trigger event to satisfy the condition
  • Approval Requirement
    • approver: Required, approver, supports users and roles
    • title: Optional, String, approval title
    • agreeEvent: Optional, custom event triggered when clicking agree (web_trigger only)
    • rejectEvent: Optional, custom event triggered when clicking reject (web_trigger only)

  See Custom Deployment Preconditions section below for examples.

Custom Deployment Preconditions

Preconditions can be defined for each environment, and deployment can only proceed if all preconditions are met. The following three types 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.

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:
      - environmentName: development
  - name: production
    description: Production environment
    require:
      - environmentName: staging
        after: 1800 # Requires staging deployed 30 minutes ago

Annotation Preconditions

.cnb/tag_deploy.yml

environments:
  - name: production
    description: Production environment
    require:
      - annotation: key1 # Must have a value
      - annotation: key2
        expect:
          eq: value2 # Must equal value2
      - annotation: key3
        expect:
          and:
            gt: 1
            lt: 10 # Must be >1 and <10
        button:
          - name: Generate Annotation
            event: web_trigger_annotation
            description: Generate Annotation Workflow
            env:
              name1: value1

Approval Process Preconditions

Custom approval processes and designated approvers can be defined. approver supports users and roles; meeting either one makes a user an authorized approver. users matches usernames exactly; roles is upwardly inclusive—for example, if developer is granted, then developer, master, and owner can all approve. Authorized approvers can approve or reject. The requirement is considered satisfied only when all approval steps are approved.

The roles in the deployment permission list (permissions) also uses upward-inclusive semantics: configuring the minimum required role automatically includes all higher roles.

.cnb/tag_deploy.yml

environments:
  - name: production
    description: Production environment
    require:
      - approver:
          users:
            - user1
            - user2
        title: Test Approval
      - approver:
          roles:
            - developer
            - master
        title: Development Approval
      - approver:
          users:
            - user4
          roles:
            - master
            - owner
        title: Operations Approval

Custom Deployment Pipelines

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

.cnb.yml

$:
  tag_deploy.development: # deploy to development environment
    - name: dev
      stages:
        - name: Environment name
          script: echo $name
        - name: Tag name
          script: echo $tag_name

  tag_deploy.staging: # deploy to staging environment
    - name: dev
      stages:
        - name: Environment name
          script: echo $name
        - name: Tag name
          script: echo $tag_name

  tag_deploy.production: # deploy to production environment
    - name: dev
      stages:
        - name: Environment name
          script: echo $name
        - name: Tag name
          script: echo $tag_name

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 writes Annotation when executed.

.cnb.yml

$:
  web_trigger_annotation:
    - stages:
        - name: Write Annotation
          image: cnbcool/annotations:latest
          settings:
            data: |
              key1=value1
              key2=value2

Deployment Permissions

By default, users with repository write permission and tag push permission can deploy.

If the permissions field is configured, users must have both repository write permission and the permissions defined in the permissions field. In this case, tag push permission is no longer checked.

Custom buttons (button, including those in pre-deployment conditions require) triggering web_trigger events require deployment permission of the environment. If the button itself configures permissions, the user must also be listed in its users / roles.

Rebuild Restrictions

To prevent deployment operations from being replayed by others, builds triggered by deployment events (tag_deploy.*) have the following rebuild restrictions:

• Only the original pipeline trigger can rebuild; other users cannot.
• Rebuild is only allowed within 24 hours after the original build; rebuilds are not allowed after 24 hours.

If a redeployment is needed after 24 hours or by a different user, please initiate a new deployment from the Tag details page to ensure pre-deployment checks and approval workflows are followed.

Previous pageManually Trigger Pipeline

Next pageOIDC Integration