Cloud Native Build will fetch and parse the .cnb.yml configuration file from the corresponding branch when an event is received. It retrieves the pipeline configuration for the corresponding event under that branch and then assigns a Runner to execute the build.

Take the push event of the main branch code as an example:

Code example:

# .cnb.yml
main: # Trigger branch
  push: # Trigger event, corresponding to a build, can contain multiple Pipelines. It can be either an array or an object.
    - stages: # Pipeline 1
        - echo "do some job"
    - stages: # Pipeline 2
        - echo "do some job"

Trigger Branch

Corresponds to the branch of the code repository, used to match the branch corresponding to the event and specify the pipeline configuration.

Note: Configuring pipelines for other branches in .cnb.yml under a certain branch does not mean that events from those branches will execute pipelines according to this configuration. Instead, it depends on the specific .cnb.yml configuration under each branch.

Matching Patterns

Branch names support glob pattern matching (What is glob matching?), for example:

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

Matching Strategy

Matching is done in stages, with priority. Only when there is no match result, the next stage will be attempted.

1. glob matches branch names.
2. $ fallback matches all branches not matched by glob.

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

Trigger Events

Specifies which event triggers the build. Supports configuring multiple pipelines for parallel execution.

Below is a list of events supported by Cloud Native Build.

Branch Events

Events triggered by changes in remote code branches.

push

Triggered when a branch is pushed.

commit.add

Triggered when there are new Commits during a branch push.

This event includes an additional environment variable CNB_NEW_COMMITS_COUNT, which represents the number of new Commits, with a maximum value of 99.

You can use git log -n to view the newly added Commits.

branch.create

Triggered when a branch is created, and it 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 is already deleted when the pipeline runs).

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 Events

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

pull_request

Triggered by PR creation, reopening, and source branch push. The difference from pull_request.target is explained in Code Version Selection.

pull_request.update

Triggered by PR creation, reopening, source branch push, and PR title or description changes.

pull_request is a subset of pull_request.update,i.e., changes to PR title or description trigger pull_request.update but not pull_request.

PR creation, reopening, and source branch push trigger both pull_request and pull_request.update.

pull_request.target

Triggered by PR creation, reopening, and source branch push. The difference from pull_request is explained in Code Version Selection.

pull_request.mergeable

Triggered when an open PR meets the following conditions:

1. The target branch is a protected branch and the following rules are checked:
   1. Requires reviewer approval.
   2. Needs to pass status checks (optional).
2. Mergeable:
   1. No code conflicts.
   2. Status checks passed (if status checks are required and there are status checks).
3. Review approved.

The configuration file for this event is taken from the target branch. Refer to Code Version Selection.

The pipeline will only execute if the target branch of the PR has configured this event.

pull_request.merged

Triggered when a PR is successfully merged.

Tips

Merging branch a into branch b triggers pull_request.merged and push events under branch b.

pull_request.approved

Triggered when a user reviews a PR and approves it.

Tips

If the protected branch requires multiple reviewers, a user's approval does not mean the PR is in an approved state.

pull_request.changes_requested

Triggered when a user reviews a PR and requests changes.

pull_request.comment

Triggered when a comment is created on a PR.

Tag Events

Events triggered by Tag related operations in remote code or the page.

tag_push

Triggered when a Tag is pushed.

Example:

# Effective for specified tags
v1.0.*:
  tag_push:
    - stages:
        - name: echo tag name
          script: echo  $CNB_BRANCH

# Effective for all tags
$:
  tag_push:
    - stages:
        - name: echo tag name
          script: echo  $CNB_BRANCH

auto_tag

Automatically generated Tag event.

1. Trigger Method

   Only triggered by clicking the Auto Generate Tag button on the repository's Tag list page.

2. Implementation Principle

   Starts a pipeline, defaulting to the cnbcool/git-auto-tag plugin to automatically generate a Tag.

3. Format Description

   The Tag defaults to the 3.8.11 format. If the latest Tag starts with v, the automatically generated Tag will also include v, such as v4.1.9.

4. Custom auto_tag Event Pipeline

   Users can add the following configuration in the root directory .cnb.yml file 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

   Note: The default configuration will be merged with .cnb.yml, and the configuration in the latter under the same branch name will override the former. If the auto_tag configuration in .cnb.yml is under $ instead of the default branch name, both auto_tag configurations will be retained, but the configuration under $ will be ignored. Refer to the include merge rules for the merge mode.

tag_deploy.*

Events triggered by the Deploy button on the repository Tag/Release page.

Details refer to Deployment.

Issue Events

Events triggered by Issue related operations.

Issue event pipeline configurations need to be attached to $.

issue.open

Triggered when an Issue is created.

issue.close

Triggered when an Issue is closed.

issue.reopen

Triggered when an Issue is reopened.

api_trigger Custom Event

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

Methods 1 and 2 are encapsulations of method 3.

web_trigger Custom Event

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

Only triggered on the page.

Use cases:

• Can be combined with Deployment capabilities.
• Custom Buttons on the page.

Manually trigger builds (supports inputting environment variables, only triggers web_trigger events).

Scheduled Task Events

Events triggered by scheduled tasks.

Details refer to Scheduled Tasks.

Workspace Events

Events triggered by clicking the Workspace button on the page.

Details refer to Workspace.

Code Version Selection

When an event is triggered, the corresponding code version needs to be determined to fetch, parse the corresponding .cnb.yml, and checkout the code to execute the pipeline. Usually, the code version aligns with intuition and the triggering branch, but for some events like PR related or branch.delete, additional considerations are made, and the code version may differ from the triggering branch.

Below is a list of how Cloud Native Build selects the code version for each event:

1. For push,commit.add, branch.create, and vscode events, the latest commit of the current branch is selected.
2. For auto_tag, branch.delete, and issue.* events, the latest commit of the default branch is selected.
3. For tag_push and tag_deploy.* events, the current Tag is selected.
4. For pull_request, pull_request.update, pull_request.approved, and pull_request.changes_requested events, which involve source and target branches, the pre-merged code version is selected.
5. For pull_request.merged events, the post-merged code version is selected.
6. For pull_request.target and pull_request.mergeable events, the latest commit of the target branch before merging is selected.
7. For api_trigger custom events, the version can be specified. cnb:apply restricts it to the code version of the current pipeline.
8. For web_trigger custom events, the configuration file is read from the corresponding branch or Tag, depending on the specific use case.
9. For scheduled task events, the configuration file is read from the specified branch.
10. For rebuilds, the code version of the current build is selected.