CNB

Events

# Event-Driven

The Cloud Native Build pipeline is triggered by events. Let's take the push event as an example to explain the process from code changes to pipeline execution:

  1. Users commit code and push it to the remote server (CNB).

  2. The Cloud Native Build receives the push event trigger request and analyzes information such as repository, event, and branch.

  3. The Cloud Native Build retrieves the configuration file (default: .cnb.yml) from the repository branch and parses the pipeline configuration corresponding to the event.

  4. The Cloud Native Build executes the pipeline.

If multiple events are triggered, such as creating a branch triggering both branch.create and push, the corresponding events in the configuration file will be treated as different builds and executed in parallel.

Multiple event example:

dev/1:
  push:
    - stages:
        - name: echo
          script: echo 1
# Match branch.create events for all branches
(**):
  branch.create:
    - stages:
        - name: echo
          script: echo 2

# Git Events

Git events are triggered by remote code operations.

# push

Branch push event.

# branch.create

Branch creation event, also triggers the push event.

# branch.delete

Branch deletion event.

Pipeline configurations can be attached to branch names or $.

The pipeline will use the configuration file of the default branch (reason: the branch has been deleted at runtime).

Example:

dev/1:
  branch.delete:
    - stages:
        - name: echo
          # CNB_BRANCH value is the deleted branch
          script: echo $CNB_BRANCH
$:
  branch.delete:
    - stages:
        - name: echo
          # CNB_BRANCH value is the deleted branch
          script: echo $CNB_BRANCH

# pull_request

Branch merge event triggered by the creation, reopening, and source branch push of a PR. Refer to Configuration File for the difference between pull_request and pull_request.target.

Example: Dynamic Notification of Pull Requests to a Group

# pull_request.target

Branch merge event triggered by the creation, reopening, and source branch push of a PR. Refer to Configuration File for the difference between pull_request and pull_request.target.

# pull_request.approved

Branch merge event triggered when a user approves the PR for merging.

TIP

Note that having a user approve the PR does not necessarily mean that the PR is in an approved state, as protected branches may require multiple reviewers' approval.

# pull_request.changes_requested

Branch merge event triggered when a user requests changes to be made in the PR.

Example: Dynamic notification to a group for PR

# pull_request.mergeable

Triggered when an open PR meets the following conditions:

  1. The target branch is a protected branch with the following rules checked:
    1. Requires approval from reviewers
    2. Requires passing status checks
  2. It is mergeable:
    1. No code conflicts
    2. Passes status checks (if any)
  3. Approved by reviewers

Example: Dynamic notification to a group for PR

# pull_request.merged

Event triggered when a branch is successfully merged.

TIP

When branch a is merged into branch b, it triggers the pull_request.merged and push events under branch b.

Example: Dynamic notification to a group for PR

# tag_push

tag push event.

Example:

v*:
  tag_push:
    - stages:
        - name: echo
          # CNB_BRANCH value is the tag name
          script: echo $CNB_BRANCH

# vscode

Event triggered by clicking the "Cloud Native Development" button on the page.

Refer to Customize the Creation Process for Cloud Native Development

# auto_tag

Event for automatically generating tags, with the event name auto_tag.

  1. Trigger Method: It only supports triggering cloud-native builds by clicking the "Auto Generate Tag" button on the tag list page of the repository. The cloud-native build will start a pipeline to automatically generate tags. The pipeline uses the cnbcool/git-auto-tag image to implement automatic tag generation. Tag Format Explanation: By default, the tag format is 0.0.1 or a similar format. If the latest tag starts with v, the automatically generated tag will also include the v prefix, such as v0.0.1.

  2. How to Customize the Pipeline for Auto-Generating Tags:

Users can add a .cnb.yml file in the root directory and include the following configuration format to override the default template.

# User-defined .cnb.yml configuration
main: # Default branch, can be replaced with the actual default branch of the repository
  auto_tag: # Event name
    - stages:
        - name: Auto-generate Tag
          image: "cnbcool/git-auto-tag:latest"
          settings:
            tagFormat: 'v\${version}'
            branch: $CNB_BRANCH
            repoUrlHttps: $CNB_REPO_URL_HTTPS
          exports:
            tag: NEW_TAG
        - name: show tag
          script: echo $NEW_TAG

# tag_deploy.*

Events triggered by the deployment button on the tag/release page of the repository, see documentation

# Issue Events

Issue events are triggered by actions such as creating or closing an issue.

Pipeline configurations for issue events should be placed under $.

# issue.open

Event triggered when an issue is created.

Example: Notification of issues to an enterprise WeChat group

# issue.close

Event triggered when an issue is closed.

# issue.reopen

Event triggered when a closed issue is reopened.

# Custom Events

Custom events must have event names that are either api_trigger or start with api_trigger_, such as api_trigger_test.

There are two ways to trigger custom events:

  1. Triggered by cnb:apply
  2. Triggered by cnb:trigger

# Web Page Custom Events

Web page custom events must have event names that are either web_trigger or start with web_trigger_, such as web_trigger_test.

These events can only be triggered on the web page.

Use Cases:

  • Can be used in conjunction with Deployment capabilities
  • You can define a Custom Button on the page to manually trigger builds (supporting input of environment variables, only supports triggering the web_trigger event)

# Crontab Events

Crontab events are triggered by crontab. For more details, please refer to the Crontab documentation.

# Branch Matching

# Matching Branches with glob Patterns

Branch names can be matched using glob patterns (learn more about glob matching (opens new window)). For example:

# Match all branches starting with dev/
"dev/*":
  push:
    - push_pipeline

# Match main or dev branches
"(main|dev)":
  push:
    - push_pipeline

# Match all branches except main and dev
"**/!(main|dev)":
  push:
    - push_pipeline

# Match all branches
"**":
  push:
    - push_pipeline

# Fallback, match branches not matched by glob patterns
"$":
  tag_push:
    - push_pipeline

# Matching Strategy

The matching strategy follows a staged approach, where matching is done based on priority. Only if there is no match in the previous stage, the next stage is attempted.

  1. Match branch names using glob patterns.
  2. Fallback to match all branches not matched by glob patterns using $.

If multiple glob rules match, all matched rules will be executed in parallel.

# Skipping Pipelines

In push and branch.create events, the pipeline will be skipped under the following conditions:

  1. The most recent commit message contains [ci skip] or [skip ci].
  2. The git push -o ci.skip command is used.

For example:

git commit -m "feat: Add some feature [ci skip]"
git push origin main

or

git commit -m "feat: Add some feature"
git push origin main -o ci.skip

# Configuration File Version Selection

Since configuration files are stored in the project repository and are subject to Git version control, there may be multiple versions of the configuration file. During the build process, developers need to know which version of the configuration file to use. Fortunately, the Cloud Native Build mechanism is very intuitive, and in most cases, developers do not need to worry about this.

The following describes how Cloud Native Build selects which version of the configuration file to use in each event. It is important to note that the pull_request event has a more complex selection process:

  1. For push, branch.create, and vscode events, the configuration file is read from the latest commit node of the current branch.
  2. For auto_tag, branch.delete, and issue.* events, the configuration file is read from the default branch.
  3. For tag_push and tag_deploy.* events, the configuration file is read from the current tag.
  4. For pull_request, pull_request.approved, and pull_request.changes_requested events, where there is a source branch and a target branch, the configuration file is read from the pre-merged configuration file.
  5. For pull_request.merged events, the configuration file is read from the merged configuration file.
  6. For pull_request.target and pull_request.mergeable events, the configuration file is read from the configuration file of the target branch before merging.
  7. For custom events, please refer to cnb:apply and cnb:trigger.
  8. For web page custom events, the configuration file is read from the corresponding branch or tag. Please refer to the specific use case documentation.
  9. For crontab events, the configuration file is read from the specified branch.