Cloud Native Build

Events

# Event-driven

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

  1. Users submit code and push it to the remote server.

  2. The Cloud Native Build receives a push event notification and extracts information such as repository, event, branch, etc.

  3. The Cloud Native Build retrieves the configuration file .cnb.yml from the repository branch and parses the corresponding pipeline configuration based on the event.

  4. The Cloud Native Build executes the pipeline.

An operation can trigger multiple events, such as creating a branch triggering both branch.create and push events, for example:

dev/1:
  push:
    - stages:
        - name: echo
          script: echo "do something for push"
# Match branch.create event for all branches
(**):
  branch.create:
    - stages:
        - name: echo
          script: echo "do something for branch create"

The pipeline corresponding to the event in the configuration file will be executed in parallel.

The following lists the events supported by Cloud Native Build.

# Workspace Events

Events triggered by clicking the Workspace button on the page.

For more details, refer to Workspace

# Branch Events

Events triggered by changes in remote code branches.

# push

Triggered when a branch is pushed.

# branch.create

Triggered when a branch is created, also triggers the push event.

# branch.delete

Triggered when a branch is deleted.

Pipeline configurations can be attached to the branch name 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 holds the value of the deleted branch
          script: echo $CNB_BRANCH
$:
  branch.delete:
    - stages:
        - name: echo
          # CNB_BRANCH holds the value of the deleted branch
          script: echo $CNB_BRANCH

# Pull Request Events

Events triggered by remote code Pull Request related operations (referred to as PR below).

# pull_request

Triggered by PR creation, reopening, and source branch push. Refer to Configuration File for the difference from pull_request.target.

# pull_request.target

Triggered by PR creation, reopening, and source branch push. Refer to Configuration File for the difference from pull_request.

# pull_request.mergeable

Triggered when an open PR meets the following conditions:

  1. The target branch is a protected branch with the following rules enabled:
    1. Require approval from reviewers
    2. Require status checks to pass
  2. Mergeable:
    1. No code conflicts
    2. Status checks (if any) pass
  3. Approved by reviewers

# pull_request.merged

Triggered when a PR is merged.

TIP

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

# pull_request.approved

Triggered when a user approves the PR for merging.

TIP

Having a user approve the review does not necessarily mean the PR is in an approved state, as the protected branch may require multiple reviewers' approval.

# pull_request.changes_requested

Triggered when a user requests changes to be made in the PR.

# Tag Events

Events triggered by remote code and page Tag related operations.

# tag_push

Triggered when a Tag is pushed.

Example:

# match v1.0.0.x
v1.0.*:
  tag_push:
    - stages:
        - name: echo tag name
          script: echo  $CNB_BRANCH

# match all
$:
  tag_push:
    - stages:
        - name: echo tag name
          script: echo  $CNB_BRANCH

# auto_tag

Automatically generated Tag event.

  1. Triggering method:

    Only supported on the repository's Tag list page, by clicking the Automatically generate Tag button.

  2. Implementation principle:

    Starts a pipeline using the cnbcool/git-auto-tag plugin by default to automatically generate Tags.

  3. Format description:

    The Tag is in the format of 3.8.11 by default. If the latest Tag starts with v, the automatically generated Tag will also include the v, such as v4.1.9.

  4. Customizing the auto_tag event pipeline:

    Users can add a .cnb.yml file in the root directory and add the following configuration 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 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 clicking the Deploy button on the repository's Tag/Release page.

For more details, refer to Deployment

# Custom Events

Custom events are triggered by API, crontab tasks, and page-related operations.

# API Custom Events

The event name is api_trigger or starts with api_trigger_, such as api_trigger_test.

API custom events can be triggered in the following three ways:

  1. Triggered by cnb:apply
  2. Triggered by cnb:trigger
  3. Triggered by the API

Methods 1 and 2 are encapsulations of method 3

# Page Custom Events

The event name is web_trigger or starts with web_trigger_, such as web_trigger_test.

Only supported for triggering events on the page.

Use cases:

Manually trigger a build (supports inputting environment variables, only supports triggering web_trigger events)

# Crontab Task Events

Events triggered by crontab tasks.

For more details, refer to Crontab Tasks.

# Issue Events

Events triggered by operations related to Issues.

The pipeline configuration for Issue events should be attached to $.

# issue.open

Issue creation event.

# issue.close

Issue closure event.

# issue.reopen

Issue reopening event.

# Branch Matching

# Matching Patterns

Branch names support matching using glob patterns (What is glob matching? (opens new window)), such as:

.push_pipeline: &push_pipeline
  - stages:
      - name: do something
        script: echo "do something"

# 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
"$":
  push:
    - *push_pipeline
  tag_push:
    - *push_pipeline

# Matching Strategy

The matching is done in stages, with priority given to each stage. Only if there is no match in the previous stage, the next stage will be attempted.

  1. glob matching of branch names
  2. $ fallback to match all branches not matched by glob patterns

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

# Skipping Pipelines

In push and branch.create events, the pipeline will be skipped in the following two cases:

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

For example:

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

or

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

# Configuration File Version Selection

Since the configuration file is in the project repository and is subject to version control by Git, the configuration file naturally has multiple versions. Knowing which version of the configuration file is used in a particular build is something that developers must be aware of. Fortunately, the mechanism of Cloud Native Build is very intuitive, and in most cases, developers do not need to worry about it.

Below are the rules for selecting which version of the configuration file to use in each event. It is worth noting that the pull_request event has a relatively complex selection process:

  1. For push, branch.create, and vscode events, the configuration file is read from the latest commit node on 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, there are source and target branches, and the configuration file is read from the pre-merged state.
  5. For pull_request.merged events, the configuration file is read from the merged state.
  6. For pull_request.target and pull_request.mergeable events, the configuration file is read from the target branch before merging.
  7. For API custom events, the version can be specified, and cnb:apply is limited to the version corresponding to the current pipeline.
  8. For page custom events, the configuration file is read from the corresponding branch or Tag, depending on the specific use case.
  9. For crontab task events, the configuration file is read from the specified branch.