When Cloud Native Build receives various events, it automatically retrieves the .cnb.yml from the corresponding branch of the repository, parses the pipeline configuration for that event, and assigns a Runner to execute it.

Trigger Mechanism Overview

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

Event Type	Description
Git Operation Events	Code push, branch creation, PR operations, etc.
Page Operation Events	Manual trigger, button clicks, AI feature operations, etc.
API Request Events	Triggered through OPENAPI or built-in tasks
Scheduled Task Events	Triggered according to predetermined time schedules
Issue Events	Issue operations, comments, etc.
NPC Events	Triggered when @npc appears in Issue or PR descriptions and comments

Trigger Flow Example

Taking the main branch code push event as an example, the trigger flow is as follows:

Code example:

.cnb.yml

main: # Trigger branch
  push: # Trigger event, corresponding to a 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"

Fork Repository Trigger Restrictions

Forked repositories will not execute pipelines by default for the following event types:

• Git Operation Events
• Scheduled Task Events
• Issue Events

Enable Fork Repository Auto-Trigger

To allow these events to trigger pipelines, go to Settings → Cloud Native Build on the repository page and check the following options:

Setting Option	Description
Allow Auto Trigger	When checked, the repository will automatically trigger Cloud Native Build according to .cnb.yml configuration
Forked Repositories Allow Auto Trigger by Default	When checked, repositories forked from this repository will automatically trigger Cloud Native Build according to .cnb.yml configuration

Security Note: When executing pipelines, Forked repositories have their default environment variable CNB_TOKEN scoped only to the current repository to ensure security.

Trigger Branch

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

Important Note

Configuring pipelines for other branches under a specific branch will not cause events from other branches to execute according to this configuration. Actual execution depends on each branch's own .cnb.yml file.

Matching Patterns

Branch names support glob pattern matching (learn about glob matching).

Glob Matching Rules

• * matches any character except /. For example, dev/* matches dev/feature but not dev/team/feature.
• ** matches any character including /. For example, dev/** matches both dev/feature and dev/team/feature.

Use ** when branch names contain multiple / levels.

Common Matching Rules

.cnb.yml

.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

The system performs branch matching in stages according to priority, only entering the next stage when the previous stage does not match:

Priority	Matching Stage	Description
1	Glob Pattern Matching	Try to match branch names with all glob rules
2	Fallback Matching	Use $ rule to match all branches not matched by glob

Parallel Execution: If multiple glob rules match simultaneously, pipelines for all matching rules will execute in parallel.

Trigger Events

Git Operation Events

Branch Events

Events triggered by remote code branch changes.

Event Name	Trigger Timing	Description
push	Triggered on branch push	The most commonly used trigger event
commit.add	Triggered when branch push contains new commits	Provides CNB_NEW_COMMITS_COUNT (number of new Commits), usable with git log -n to view
branch.create	Triggered on branch creation	Also triggers push event; if there are new commits, also triggers commit.add event
branch.delete	Triggered on branch deletion	Uses the default branch configuration file (since the branch is deleted at runtime)

branch.delete Example:

.cnb.yml

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 (hereinafter referred to as PR) related operations.

Event Name	Trigger Timing
pull_request	PR creation, reopening, source branch push
pull_request.update	PR creation, reopening, source branch push, PR title or description modification
pull_request.target	PR creation, reopening, source branch push
pull_request.mergeable	Triggered when open PR meets specific conditions
pull_request.merged	Triggered when PR merge is completed
pull_request.approved	Triggered when user reviews PR as "Allow Merge"
pull_request.changes_requested	Triggered when user reviews PR as "Changes Requested"
pull_request.comment	Triggered when PR comment is created

Difference between pull_request and pull_request.update

pull_request is a subset of pull_request.update:

• PR title, description modification → triggers pull_request.update but not pull_request
• PR creation, reopening, source branch push → triggers both pull_request and pull_request.update

Difference between pull_request and pull_request.target

For detailed differences, please refer to Code Version Selection.

pull_request.mergeable Trigger Conditions

Triggered when an open PR simultaneously meets the following conditions:

1. Target branch is a protected branch, with the following rules checked:

   • Requires reviewer approval
   • Requires passing status checks (optional)

2. Mergeable:

   • No code conflicts
   • Status checks passed (if "requires passing status checks" is checked and there are status checks)

3. Review approved

pull_request.mergeable Notes

• Configuration file is taken from the target branch, refer to Code Version Selection
• PR target branch must have this event pipeline configured for the corresponding pipeline to execute when this event is triggered

pull_request.merged Notes

When branch a is merged into branch b, it will trigger pull_request.merged and push events under branch b.

pull_request.approved Notes

Settings may require multiple reviewers for protected branches; a user passing review doesn't necessarily mean the PR is in an approved state.

Tag Events

Events triggered by remote code and page Tag related operations.

Event Name	Trigger Timing	Description
tag_push	Triggered on Tag push	Used for automated processing after Tag push
auto_tag	Triggered when Tag is automatically generated	Only supported by clicking the "Auto Generate Tag" button on the repository Tag list page
tag_deploy.*	Triggered via the "Deploy" button on the repository Tag/Release page	Details refer to Deploy

tag_push Example:

.cnb.yml

# 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

Trigger Method: Only supported by clicking the "Auto Generate Tag" button on the repository Tag list page.

Implementation Principle: Starts a pipeline, defaulting to use the cnbcool/git-auto-tag plugin to implement automatic Tag generation.

Tag Format Description:

• Default format is 3.8.11 type
• If the latest Tag starts with v, the automatically generated Tag will also have v, such as v4.1.9

Custom Configuration:

.cnb.yml

main: # Default branch, can be replaced with the actual default branch of the repository
  auto_tag:
    - stages:
        - name: release rules
          # This environment variable is passed in when triggering the build, can view print content to see 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

Configuration Override Rules

Default configuration will be merged with .cnb.yml, with the later configuration under the same branch name overriding the earlier one. If auto_tag configuration in .cnb.yml is under $ rather than the default branch name, both auto_tag configurations will be retained, but the configuration under $ will be ignored. Refer to include Merge Rules.

---

Page Operation Events

web_trigger Custom Event

Event Name Format: web_trigger or starting with web_trigger_, such as web_trigger_test.

Trigger Method: Only supported by triggering events on the page.

Usage Scenarios:

Scenario	Description
Deploy Capability	Used in combination with Deploy capability
Custom Button	Custom Buttons on the page
Manual Build Trigger	Supports inputting environment variables (only supports triggering web_trigger event)

Cloud Native Development Event

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

---

API Request Events

api_trigger Custom Event

Event Name Format: api_trigger or starting with api_trigger_, such as api_trigger_test.

Trigger Methods:

Trigger Source	Description
cnb:apply	Refer to cnb:apply
cnb:trigger	Refer to cnb:trigger
OPENAPI	Refer to OPENAPI

Tip

Methods 1 and 2 are wrappers for method 3.

---

Scheduled Task Events

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

---

Issue Events

Events triggered by Issue related operations.

Configuration Requirements

Issue event pipeline configurations need to be attached under $.

Event Name	Trigger Timing
issue.open	When Issue is created
issue.close	When Issue is closed
issue.reopen	When Issue is reopened
issue.update	When Issue name, description, assignee, labels, priority change
issue.update.assignee_change	When Issue assignee changes
issue.update.priority_change	When Issue priority changes
issue.update.label_change	When Issue labels change
issue.comment	When Issue is commented

---

NPC Events

In the following scenarios, mentioning an NPC role (such as @npc) in a description or comment will trigger the NPC event:

Scenario	Trigger Event
Issue description when creating	issue.comment@npc
Issue comment	issue.comment@npc
PR description when creating	pull_request.comment@npc
PR review	pull_request.comment@npc
PR comment	pull_request.comment@npc
PR review comment	pull_request.comment@npc

For more information, see NPC Documentation

Code Version Selection

When an event is triggered, the corresponding code version needs to be determined to retrieve and parse the corresponding .cnb.yml, checkout the code, and execute the pipeline.

Version Selection Strategy

Event Type	Code Version Selection
push, commit.add, branch.create, vscode	Latest Commit of current branch
auto_tag, branch.delete, issue.*	Latest Commit of default branch
tag_push, tag_deploy.*	Current Tag
pull_request, pull_request.update, pull_request.approved, pull_request.changes_requested, pull_request.comment	Pre-merged Commit
pull_request.comment@npc	Latest Commit of target branch (for cross-repo fork PRs, uses source repository's source branch when triggered by PR author)
issue.comment@npc	Latest Commit of default branch
pull_request.merged	Merged Commit
pull_request.target, pull_request.mergeable	Latest Commit of target branch before merge
api_trigger	Version can be specified; cnb:apply limited to current build Commit
web_trigger	Read configuration file from corresponding branch, Tag, refer to specific application scenarios
Scheduled Task	Latest Commit of specified branch
Rebuild	Current build Commit

Untrusted Events

Untrusted events refer to event types where the code source or trigger is uncontrollable.

Event List

The following events are untrusted events:

Pull Request Related Events:

• pull_request: PR creation or source branch push
• pull_request.update: PR content update (including title, description modification)
• pull_request.approved: PR approval passed
• pull_request.changes_requested: PR approval rejected
• pull_request.comment: PR comment
• pull_request.comment@npc: Triggered when @npc appears in PR descriptions or comments

Issue Related Events:

• issue.comment: Issue comment
• issue.comment@npc: Triggered when @npc appears in Issue descriptions or comments

For more information, see NPC Documentation

Risk Scenarios

PR Events:

Pipeline configuration originates from the source branch and may be modified by unauthorized users, with the following risks:

• Malicious code injection or sensitive content leakage
• Build artifacts (such as images, binary files) being tampered with
• Referencing secret repository files leading to key or credential leakage

Comment Events:

The trigger is the commenter, who may not be a repository member or administrator:

• Accessing commenter resources leading to data leakage
• Tampering with commenter resources causing damage

NPC Events:

The pipeline can be provided by the NPC's repository, and the trigger is the commenter, with stacked risks:

• NPC configuration source is uncontrollable and may be maliciously tampered with
• Both commenter resource leakage and tampering risks exist simultaneously

Security Measures

To reduce the above risks, the system takes the following protective measures for untrusted events:

Security Measure	Description
CNB_TOKEN Permission Restriction	The CNB_TOKEN built into the pipeline environment variables has strictly limited permissions to prevent unauthorized access
File Reference Explicit Declaration	When untrusted event pipelines reference external files, the referenced files must explicitly declare through allow_events which events are allowed to reference them, avoiding sensitive files being accidentally referenced

Usage Recommendations

Security Recommendations

• Choose Trusted NPCs: When commenting, prioritize NPC roles provided by trusted repositories
• Isolate Sensitive Tasks: Tasks involving key operations, sensitive data processing, and other important content are recommended to be executed in trusted events such as push, pull_request.target, tag_push

Previous pageQuick Start

Next pageConfiguration File