When Cloud Native Build receives various events, it automatically fetches the .cnb.yml configuration file from the corresponding branch, parses the pipeline configuration for the specific event under that branch, and assigns a Runner to execute the build task.

Trigger Mechanism Overview

Cloud Native Build supports multiple event trigger methods, mainly including:

1. Git Operation Events: Code push, branch creation, PR operations, etc.
2. Page Operation Events: Manual triggers, button clicks, AI function operations, etc.
3. API Request Events: Triggered via OPENAPI or built-in tasks
4. Scheduled Task Events: Triggered according to a predefined schedule
5. System Events: Issue operations, Issue or PR comments, etc.

Taking the push event on the main branch as an example, the trigger process is as follows:

Code Example:

.cnb.yml

main: # Trigger branch
  push: # Trigger event, corresponds to one build, can contain multiple Pipelines. Can be an array or an object.
    - stages: # Pipeline 1
        - echo "do some job"
    - stages: # Pipeline 2
        - echo "do some job"

Trigger Branch

The trigger branch refers to the branch in the code repository where the event occurs, used to match the corresponding pipeline configuration.

Important Note: Configuring pipelines for other branches within a specific branch's configuration will NOT cause events on those other branches to execute using that configuration. Actual execution depends on the .cnb.yml file present in each branch itself.

Matching Patterns

Branch names support glob pattern matching (Learn about 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 branch
"(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 any glob pattern
"$":
  push:
    - *push_pipeline
  tag_push:
    - *push_pipeline

Matching Strategy

The system matches branches in stages by priority, proceeding to the next stage only if the previous one finds no match:

1. Glob Pattern Matching: Attempts to match the branch name against all glob rules.
2. Fallback Matching: Uses the $ rule to match all branches not matched by any glob pattern.

If multiple glob rules match simultaneously, the pipelines from all matching rules will execute in parallel.

Trigger Event Types

Git Operation Events

Branch Events

Events triggered by changes to remote code branches.

push: Triggered when a branch is pushed.

commit.add: Triggered when a branch push includes new commits. This event provides an additional environment variable CNB_NEW_COMMITS_COUNT, indicating the number of new commits. Can be used with git log -n to view the new commits.

branch.create: Triggered when a branch is created. Also triggers the push event. If there are new commits, it will also trigger the commit.add event.

branch.delete: Triggered when a branch is deleted. The pipeline configuration can be attached either under the branch name or under $. The pipeline will use the configuration file from 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 (PR) related operations.

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

pull_request.update: Triggered by PR creation, reopening, source branch pushes, and modifications to the PR's title or description.

Note: pull_request is a subset of pull_request.update. Modifications to the PR's title or description trigger pull_request.update but not pull_request. PR creation, reopening, and source branch pushes trigger both pull_request and pull_request.update.

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

pull_request.mergeable: Triggered when an open PR meets all the following conditions:

1. The target branch is a protected branch with the following rules enabled:
   • Requires reviewer approval
   • Requires status checks to pass (optional)
2. Is mergeable
   • No code conflicts
   • Status checks pass (if required and status checks exist)
3. Review is approved

The configuration file for this event is taken from the target branch, refer to Code Version Selection. The pipeline for this event will only execute if the target branch of the PR has this event configured.

pull_request.merged: Triggered when a PR merge is completed.

Merging branch a into branch b will trigger the pull_request.merged and push events on branch b.

pull_request.approved: Triggered when a user reviews the PR and approves the merge.

The protected branch settings might require multiple reviewer approvals. A user passing the review does not necessarily mean the PR is in an approved state.

pull_request.changes_requested: Triggered when a user reviews the PR and requests changes.

pull_request.comment: Triggered when a PR comment is created.

Tag Events

Events triggered by remote code and page Tag related operations.

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: Auto-generate Tag event.

1. Trigger Method: Only triggered by clicking the Auto Generate Tag button on the repository's Tag list page.
2. Implementation Principle: Launches a pipeline, defaulting to using the cnbcool/git-auto-tag plugin to automatically generate the Tag.
3. Format Description: The Tag defaults to a format like 3.8.11. If the latest Tag starts with v, the auto-generated Tag will also include v, e.g., v4.1.9.
4. Custom Configuration: Users can override the default template by adding the following configuration to the root directory .cnb.yml file:

# User-defined .cnb.yml configuration
main: # Default branch, can be replaced with the actual default branch of the repo
  auto_tag: # Event name
    - stages:
        - name: release rules
          # This environment variable is passed in when the build is triggered. You can check the printed content to see the release rules.
          script: echo -e "$RELEASE_RULES"
        - name: auto tag
          image: cnbcool/git-auto-tag:latest
          settings:
            tagFormat: 'v\${version}'
            branch: $CNB_BRANCH
            repoUrlHttps: $CNB_REPO_URL_HTTPS
            releaseRules: $RELEASE_RULES
          exports:
            tag: NEW_TAG
    - name: show tag
      script: echo $NEW_TAG

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

tag_deploy.*: Events triggered by the Deploy button on the repository's Tag/Release page. Details refer to Deployment.

Page Operation Events

web_trigger Custom Events

Event names are web_trigger or start with web_trigger_, e.g., web_trigger_test.

Trigger Method: Only triggered via the page.

Use Cases:

• Can be used in combination with Deployment capabilities.
• Custom buttons on the page.
• Manual build triggering (supports inputting environment variables, only triggers web_trigger events).

AI Related Events

Pipeline events triggered by AI-related buttons on the page.

ai_issue: Based on Issue content, AI automatically codes and submits a PR to the repository.

1. Trigger Method: Only triggered by clicking the AI Auto-Submit PR button on the repository's Issue details page.
2. Implementation Principle: Launches a pipeline where AI is used to automatically code based on the issue content and submit a PR.

ai_review: Based on the git diff content of a PR, AI performs a code review and submits the review as a PR comment.

1. Trigger Method: Only triggered by clicking the AI Review button on the repository's PR details page.
2. Implementation Principle: Launches a pipeline where AI is used to perform a code review based on the PR's git diff content and submit the review as a PR comment.
3. Custom Configuration: Users can override the default template by adding the following configuration to the root directory .cnb.yml file:

In the following pipeline, the image plugin used is cnbcool/ai-review:latest, and parameters can be customized as needed.

# User-defined .cnb.yml configuration
# $: Matches all branches not matched by other configurations.
$:
  ai_review: # Event name
    - stages:
        - name: AI code review
          image: cnbcool/ai-review:latest
          settings:
            # Only publish comments for scores below 60.
            score: 60
            # The maximum number of comments to be published.
            max_comments: 5
            # The following four parameters can directly use the environment variables passed when the button is clicked, with no need to configure your own environment variables.
            # pull_request source branch
            from: $PULL_REQUEST_FROM
            # pull_request target branch
            to: $PULL_REQUEST_TO
            # pull_request title
            title: $PULL_REQUEST_TITLE
            # pull_request id
            iid: $PULL_REQUEST_IID

Workspace Events

Events triggered by clicking the Workspace button on the page. Details refer to Workspace.

API Request Events

api_trigger Custom Events

Event names are api_trigger or start with api_trigger_, e.g., api_trigger_test.

Trigger Methods:

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

Methods 1 and 2 are wrappers around method 3.

Scheduled Task Events

Events triggered by scheduled tasks. Details refer to Scheduled Tasks.

System Events

Issue Events

Events triggered by Issue related operations. Issue event pipeline configurations must be attached under $.

issue.open: Triggered when an Issue is created.

issue.close: Triggered when an Issue is closed.

issue.reopen: Triggered when an Issue is reopened.

issue.update: Triggered by changes to the Issue's name, description, assignee, labels, or priority.

issue.update.assignee_change: Triggered by changes to the Issue's assignee.

issue.update.priority_change: Triggered by changes to the Issue's priority.

issue.update.label_change: Triggered by changes to the Issue's labels.

issue.comment: Triggered by Issue comments.

Code Version Selection

When an event is triggered, the corresponding code version needs to be determined to fetch, parse the corresponding .cnb.yml, checkout the code, and execute the pipeline. The code version selection strategy for different events is as follows:

1. push, commit.add, branch.create, vscode events: Select the latest Commit of the current branch.
2. auto_tag, branch.delete, issue.* events: Select the latest Commit of the default branch.
3. tag_push, tag_deploy.* events: Select the current Tag.
4. pull_request, pull_request.update, pull_request.approved, pull_request.changes_requested、pull_request.comment events: Take the pre-merged Commit.
5. pull_request.merged event: Take the post-merge Commit.
6. pull_request.target, pull_request.mergeable events: Take the latest Commit of the target branch before merging.
7. api_trigger custom events: Can specify a version. cnb:apply is restricted to the current build's Commit.
8. web_trigger custom events: Read the configuration file from the corresponding branch/Tag, refer to the specific use case.
9. Scheduled task events: Read the configuration file from the latest Commit of the specified branch.
10. Rebuild: Take the current build's Commit.

Warning

Security Reminder: Risks of Cross-Repository or Non-Protected Branch PRs to Protected Branches

When a Pull Request (PR) is submitted from a cross-repository or non-protected branch to a protected branch, code, artifacts, keys, and other resources temporarily fall outside the direct control of the repository administrator or developer. Such operations may pose the following risks:

1. Code Security: Malicious code injection, dependency vulnerabilities, and sensitive code leakage.
2. Artifact Security: Tampering with built images or binary files, leading to supply chain attacks.
3. Key Exposure: Improper use of API keys, credentials, and other sensitive information.

Security Measures

To mitigate the above risks, the following measures have been implemented for pre-merge PR events (as per the fourth code version selection):

1. Permission Restrictions: The permissions of the built-in CNB_TOKEN in the pipeline environment variables will be restricted.
2. Key File Reference Restrictions: Key files can only be referenced by the pipeline for the above events if one of the following conditions is met:
   • The pipeline trigger has the corresponding key repository permissions, and the key file does not declare any allow_ attributes;
   • The key file explicitly declares allow_events and includes the above events.

Recommendations

For tasks involving sensitive or critical content, it is recommended to execute them in non-PR-related events to further reduce risks.