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 not upwardly inclusive.

• 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.
  • 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) + after (optional, in seconds)
  • Annotation Requirement: annotation (required) + expect (optional, supports eq/ne/gt/lt/gte/lte/and/or/reg)
  • Approval Requirement: approver (required, supports users and roles), title (optional), agreeEvent/rejectEvent (optional)

  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. 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:
      - 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 performs deployment operations 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 perform deployment operations.

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.

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 pageMigrating from GitHub Actions to CNB