Custom Deployment Process
About 2893 wordsAbout 10 min
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: 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, 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
# 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
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: value2name: Required, environment name, must be unique. Example:name: development- clicking deploy button for this environment triggerstag_deploy.developmentevent pipeline in.cnb.ymldescription: 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 pipelinepermissions: 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. 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).- Environment requirement parameters:
environmentName: Required. Environment name.after: Optional. Time in seconds. IndicatesenvironmentNamemust have been deployed successfully for this duration.description: Optional. Description ofrequirecondition.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 supportsweb_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,Inputtype 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, descriptionplaceholder: Optional,String, Prompt information in the input box. Only valid when type isinput,textarea, orselect.required: Optional,Boolean, whether requiredtype: Optional,String, input type, can beinput,textarea,select,switch, default isinputdefault: Optional,String, default valuemultiple: Optional,Boolean, whether to support multiple selection, only valid when type=select, multiple results are separated by semicolons. Commas should be avoided in thevalueof individual optionsoptions: Optional,Array<Option>, options whentype: selectortype: switch.Optiontype is defined as follows:name: Required,String, option namevalue: Required,String, option value, used as environment variable valuedescription: Optional,String, option description
inputsalso supports grouping. It is defined asArray<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 theinputtype follows the same definition as theInputtype described above.
- Metadata requirement parameters:
annotation: Required. Metadatakey.expect: Optional. Requirements for metadatavalue. Object format supportingeq,ne,gt,lt,gte,lte,and,or,regoperators.eq: Equal tone: Not equal togt: Greater thanlt: Less thangte: Greater than or equal tolte: Less than or equal toand: ANDor: ORreg: Match a regular expression
description: Optional. Description ofrequirecondition.button: Optional. Custom button that triggers event when clicked. Button hides when condition is met.name: Required, button name.event: Required, custom event, only supportsweb_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.
- 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 likeTest 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_nameThe relationship between pipeline event names and environment types is:
tag_deploy.development:developmenttag_deploy.staging:stagingtag_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=value2Deployment 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.