--- url: /en/build/deploy.md description: > Describes how to configure custom deployment environments, approval workflows, and deployment pipelines in Cloud Native Build to achieve automated deployment with role-based permissions. --- Cloud Native Build supports custom deployment workflows with configurable deployment environments, approval processes, and deployment pipelines for automated releases. ![](/images/build/deploy-intro.en.png) ## 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: ```yaml title=".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: ```yaml title=".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: ```yaml title=".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`: ```yaml title=".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`. Array of usernames. Multiple usernames can be defined. * `roles`: Optional. `Array`. 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](./web-trigger.md#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](#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 ```yaml title=".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 ```yaml title=".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. ```yaml title=".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.` event. The pipeline deploys based on the code corresponding to the current tag. ```yaml title=".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](./trigger-rule.md#web_trigger). In the pipeline configuration below, the `web_trigger_annotation` event writes [Annotation](../repo/annotations.md) when executed. ```yaml title=".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.