Deployment

• Customizing the Deployment Environment
• Customizing the Deployment Pipeline
• Custom Button Triggered web_trigger Event
• Deployment Permission Explanation

Deployment Method: You can click the deployment button on the repository's tag list page, select the deployment environment type, and trigger the deployment pipeline to execute the deployment event.

Deployment Event Name: It starts with tag_deploy. For example, if the environment name is development, the event name will be tag_deploy.development.

Users can customize the deployment environment and deployment pipeline:

Customizing the Deployment Environment

Add a .cnb/tag_deploy.yml file in the root directory of the repository to configure the deployment environment. The example below defines three environments: development, staging, and production. Users can select the desired environment type on the page for deployment.

# .cnb/tag_deploy.yml
environments:
  - name: development
    description: Development environment
    # Environment Variables (When a pipeline is triggered, environment variables will be passed into the pipeline, including deployment pipeline and web_trigger pipeline)
    env:
      name: development
      # CNB_BRANCH: Environment variable, in the tag_push event, it represents the tag name
      tag_name: $CNB_BRANCH

  - name: staging
    description: Staging environment
    env:
      name: staging
      # CNB_BRANCH: Environment variable, in the tag_push event, it represents the tag name
      tag_name: $CNB_BRANCH

  - name: production
    description: Production environment
    # Environment Variables (When a pipeline is triggered, environment variables will be passed into the pipeline, including deployment pipeline and web_trigger pipeline)
    env:
      name: production
      # CNB_BRANCH: Environment variable, in tag_push event, it is the tag name
      tag_name: $CNB_BRANCH
    button:
      - name: Create Approval Request
        # You need to define the web_trigger_approval event pipeline in .cnb.yml
        event: web_trigger_approval
        # Environment variables passed to the web_trigger_approval event pipeline
        # Can inherit environment variables from the previous level, with a higher priority than the previous level environment variables
        env:
          name1: value1
          name2: value2

    # require Pre-conditions that must be met for the current environment deployment, supporting checks for the environment and annotation, supporting array format (array elements can be strings or objects)
    require:
      # 1. Array elements as strings (only supports deployment environments)
      - development

      # 2. Array elements as objects (supports deployment environments and annotation)
      # Deployment environment: staging environment deployment is successful after 30 minutes
      - environmentName: staging
        after: 1800

      # annotation: The value corresponding to the key key1 is not empty, meaning it has a value.
      - annotation: key1

      # annotation：The value corresponding to the key key1 must be equal to value1.
      - annotation: key1
        expect:
          eq: value1

      # annotation：The value corresponding to the key key2 must be greater than 1 and less than 10.
      - annotation: key2
        expect:
          and:
            gt: 1
            lt: 10
        # Custom button: click to trigger the execution of the web_trigger_annotation event.
        # Define a button event related to the require information, and hide the button when the require conditions are met.
        button:
          - name: generate annotation
            event: web_trigger_annotation
            # Environment variables passed to the web_trigger_annotation event pipeline
            # Can inherit environment variables from the previous level, with a higher priority than the previous level environment variables
            env:
              name1: value1
              name2: value2

    # Custom deployment button (default value: a single deployment button is displayed by default)
    # Usage scenario: When there are multiple different modules (such as repositories, CI, artifact repositories, etc.) that need to be deployed separately, multiple different buttons can be configured.
    # Note: To distinguish which module is being deployed in the deployment pipeline, you can use environment variables passed into the pipeline to make the distinction.
    deploy:
      - name: deploy button1
        description: deploy button1 description
        # Environment variables (when triggering the deployment pipeline, environment variables will be passed into the pipeline), have a higher priority than the upper-level env.
        env:
          name1: value1
          name2: value2
      - name: deploy button2
        description: deploy button1 description
        # Environment variables (when triggering the deployment pipeline, environment variables will be passed into the pipeline), have a higher priority than the upper-level env.
        env:
          name1: value1
          name2: value2

• name: Required. The name of the environment, must be unique.
• description: Optional. Description of the environment.
• env: Optional. Environment variables passed to the deployment pipeline. Users can pass the required environment variables as needed, such as the environment name and tag name in the above configuration.
• button: Optional. An array of objects. Custom buttons that trigger the cloud-native build pipeline and execute the custom web_trigger event.
  • name: Button name.
  • event: Custom event, only supports the web_trigger event.
  • env: Optional, environment variables passed to the web_trigger pipeline, which can inherit environment variables from the previous level and have a higher priority than the previous level environment variables.
• deploy: Optional, in an array of objects format. Custom deployment buttons, clicking the button can trigger the cloud-native build pipeline to execute custom web_trigger events
  • name: Required, name of the button
  • description: Optional, description of the button
  • env: Optional, environment variables passed to the deployment pipeline, higher priority than the env at the previous level
• require: Optional, in a format of either array of strings or array of objects, where after is optional. The prerequisites for deployment, deployment operation can only be performed when the prerequisites are met. Parameters corresponding to the deployment environment include: environmentName, after, button、description, Parameters corresponding to annotation include: annotation, expect, button、description, where after, expect, button、description are optional.
  • environmentName: Environment name
  • after: Time, in seconds (s). It means that the prerequisites are met only after the environment with environmentName is successfully deployed and after the specified time
  • annotation: Key-value pair, where the key in the key-value pair is the annotation key and the value in the key-value pair is the annotation value
  • expect: Expected value, in object format, supporting eq, ne, gt, lt, gte, lte, and, or, reg operators
    • eq: Equal to
    • ne: Not equal to
    • gt: Greater than
    • lt: Less than
    • gte: Greater than or equal to
    • lte: Less than or equal to
    • and: And
    • or: Or
    • reg: Able to match with regular expressions
  • description: The description information of require, with notes for users to understand the content required by require.
  • button: Custom button, clicking can trigger the execution of the event passed in by event. Define a button event related to the require information, and hide the button when the require conditions are met.
    • name: Required, name of the button
    • event: Required, custom event, only supports web_trigger events
    • env: Optional, environment variables passed to the web_trigger pipeline, which can inherit environment variables from the previous level and have a higher priority than the previous level environment variables.

Customizing the Deployment Pipeline

The example below defines deployment event pipelines for three environments. When you select the development environment for deployment, it triggers the tag_deploy.development event. The pipeline deploys based on the code corresponding to the current tag.

# .cnb.yml
$:
  tag_deploy.development:
    - name: dev
      stages:
        - name: Deployment Environment
          script: echo $name
        - name: Tag Name
          script: echo $tag_name
  tag_deploy.staging:
    - name: staging
      stages:
        - name: Deployment Environment
          script: echo $name
        - name: Tag Name
          script: echo $tag_name
  tag_deploy.production:
    - name: production
      stages:
        - name: Deployment Environment
          script: echo $name
        - name: Tag Name
          script: echo $tag_name

The mapping between the pipeline event names and the deployment environment types in the example is as follows:

• tag_deploy.development: development
• tag_deploy.staging: staging
• tag_deploy.production: production

Custom Button Triggered web_trigger Event

The custom buttons in tag_deploy.yml only support triggering web_trigger events.

In the following pipeline configuration, when the web_trigger_annotation event is executed, the upload annotation operation will be performed.

# .cnb.yml
$:
  # Events that can be triggered by custom buttons
  web_trigger_annotation:
    - stages:
        - name: Upload annotation
          image: cnbcool/annotations:latest
          settings:
            data: |
              key1=value1
              key2=value2

Deployment Permission Explanation

Only users with repository write access and push tag permissions can perform deployment operations.