---
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<String>`. Array of usernames. Multiple usernames can be defined.
  * `roles`: Optional. `Array<String>`. Array of repository roles: `owner`, `master`, `developer`, `reporter`, `guest`.
    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](./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) + `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](#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 of preconditions 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.
Authorized approvers can perform approval actions (approve or reject).
The requirement is considered satisfied only when all approval steps are approved.

```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 `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.

```yaml title=".cnb.yml"
$:
  tag_deploy.development:
    - name: dev
      stages:
        - name: Environment name
          script: echo $name
        - name: Tag name
          script: echo $tag_name
  tag_deploy.staging:
    - stages:
        - echo $name
        - echo $tag_name
  tag_deploy.production:
    - stages:
        - echo $name
        - 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 uploads [Annotation](../repo/annotations.md)
when executed.

```yaml title=".cnb.yml"
$:
  web_trigger_annotation:
    - stages:
        - name: Upload 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.