Custom Deployment Process
About 3764 wordsAbout 13 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
# 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: 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.title: Optional, Custom-triggered deployment pipeline titleenv: 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.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).- 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.
- Annotation requirement parameters:
annotation: Required. Annotationkey.expect: Optional. Requirements for annotationvalue. 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.agreeEvent: Optional, the event triggered after successfully clicking the agree approval buttondescription: Optional, description information, will be used as the pipeline title.event: Required, event name, only theweb_triggerevent 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 buttondescription: Optional, description information, will be used as the pipeline title.event: Required, event name, only theweb_triggerevent 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
aftertime 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: 1800Example: 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: value2Example: 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 ApprovalCustom 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 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=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.