Trigger Rules explains which events trigger a pipeline and how each event matches configuration in .cnb.yml.

When to use: when configuring when a build should run — for example releasing only on tag push, running checks only when a pull request is created, running on a schedule, or triggering from an API call.

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:
  push:
    - stages: # multiple stages in one job run serially in order
        - name: job 1
          script: echo "do some job"
        - name: job 2
          script: 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:

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

Organization-wide Auto-Trigger Control

Auto-trigger switches in repository settings are configured by repository admins per repository. To converge the policy across a whole root organization, root organization admins can go to Organization Settings → Cloud Native Build Control and configure the following organization-level switches:

• Allow automatic trigger by events: When disabled, no repository under the root organization will auto-trigger Cloud Native Build on repository events (push, pull request, etc.)
• Allow automatic trigger by crontab jobs: When disabled, no repository under the root organization will auto-trigger Cloud Native Build for scheduled tasks
• Allow automatic trigger by NPC: When disabled, NPCs cannot auto-trigger Cloud Native Build in any repository under the root organization

Effective rule

Auto-triggering requires both to allow: the repository switch and the root organization switch. When the organization-level switch is off, the corresponding repository-level switch no longer takes effect, and repository admins cannot bypass it from repository settings.

All three switches are enabled by default, so organizations that never configured them are unaffected.

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

The following four common matching patterns are shown individually. They can be combined in the same .cnb.yml:

Match branches starting with dev/:

.cnb.yml

"dev/*":
  push:
    - stages:
        - name: do something
          script: echo "dev branch"

Match main or dev branch:

.cnb.yml

"(main|dev)":
  push:
    - stages:
        - name: do something
          script: echo "main or dev"

Exclude main and dev:

.cnb.yml

"**/!(main|dev)":
  push:
    - stages:
        - name: do something
          script: echo "not main or dev"

Match all branches (including fallback $):

.cnb.yml

"**":
  push:
    - stages:
        - name: do something
          script: echo "all branches"
$:
  push:
    - stages:
        - name: do something
          script: echo "fallback"

Pattern	Scope
dev/*	Branches starting with dev/ (no multi-level /)
(main|dev)	main or dev branch
**/!(main|dev)	All branches except main and dev
**	All branches
$	Fallback, branches not matched by glob

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 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	Push contains new commits	Provides CNB_NEW_COMMITS_COUNT
branch.create	Triggered on branch creation	Also triggers push; also triggers commit.add with new commits
branch.delete	Triggered on branch deletion	Uses default branch latest code and config

Additional notes on branch events:

• commit.add: Provides CNB_NEW_COMMITS_COUNT (number of new Commits), usable with git log -n to view new Commits
• branch.create: Also triggers push event; if the push contains new commits, commit.add is also triggered
• branch.delete: Uses the default branch latest code and configuration file (since the branch is deleted at runtime)

branch.delete and tag_push share the same matching rules: both support exact names, glob patterns, and $ fallback. The branch.delete example is shown below, and the tag_push (Tag event) example can be found in the Tag Events section below.

.cnb.yml

# Exact match
main:
  branch.delete:
    - stages:
        - name: echo
          script: echo $CNB_BRANCH
# Fallback
$:
  branch.delete:
    - stages:
        - name: echo
          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, title/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

Additional note on pull_request.update: In addition to pull_request triggers, PR title or description modifications also trigger this event.

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.

PR scenario example: Send PR status to an Enterprise WeChat group in pull_request and pull_request.changes_requested events via the tencentcom/wecom-message plugin. We recommend injecting the Webhook URL via env (avoid hardcoding sensitive values); the example below references it uniformly through WECOM_ROBOT:

.cnb.yml

env:
  WECOM_ROBOT: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
main:
  # Notify on PR creation or update
  pull_request:
    - stages:
        - name: notice
          image: tencentcom/wecom-message
          settings:
            robot: $WECOM_ROBOT
            content: |
              > **Pull Request Needs Review:**
              > **Title:** ${CNB_PULL_REQUEST_TITLE}
              > **Creator:** ${CNB_PULL_REQUEST_PROPOSER}
              > [View Details]($CNB_EVENT_URL)

  # Notify when review changes are requested
  pull_request.changes_requested:
    - stages:
        - name: notice
          image: tencentcom/wecom-message
          settings:
            robot: $WECOM_ROBOT
            content: |
              > **${CNB_BUILD_USER} requested changes**
              > **Title:** ${CNB_PULL_REQUEST_TITLE}
              > [View Details]($CNB_EVENT_URL)

Other PR events (such as pull_request.merged and pull_request.mergeable) follow the same pattern — just change the event name and content. For available variables, see Environment Variables.

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
• When CI file parsing fails, if the target branch is a protected branch with status checks enabled, a failed status is reported to block merging. Non-protected branches do not report.

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	Auto-generated Tag trigger	See "auto_tag Auto Generate Tag" section below
tag_deploy.*	Triggered via "Deploy" btn	Details refer to Deploy

tag_push: Triggered on Tag push, supporting exact Tag names, glob patterns, and $ fallback. Configuration structure is as follows:

.cnb.yml

# Exact match
v1.0.0:
  tag_push:
    - stages:
        - name: echo
          script: echo $CNB_BRANCH
# glob pattern match
v*:
  tag_push:
    - stages:
        - name: echo
          script: echo $CNB_BRANCH
# Fallback
$:
  tag_push:
    - stages:
        - name: echo
          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. The button starts a pipeline on the branch specified by tag.auto_tag.branch (defaults to the repository default branch), which can be configured in .cnb/settings.yml via Tag Auto-Generation Configuration.

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:
  auto_tag:
    - stages:
        - name: 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
        # exports is scoped to the current Pipeline; use it in a later stage of the same Pipeline
        - 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 web_trigger)

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(Open in new window)

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

The following example attaches issue.open and issue.comment pipelines under $, so that the tasks run when an Issue is created or commented on:

.cnb.yml

$:
  issue.open:
    - stages:
        - name: notice issue
          script: echo "$CNB_ISSUE_TITLE" opened
  issue.comment:
    - stages:
        - name: notice issue
          script: echo "$CNB_ISSUE_TITLE" commented

Other events (such as issue.close, issue.update, etc.) follow the same pattern; simply replace the event name.

Issue scenario example: Send Issue status to an Enterprise WeChat group via the tencentcom/wecom-message plugin. We recommend injecting the Webhook URL via env (avoid hardcoding sensitive values); the example below references it uniformly through WECOM_ROBOT:

.cnb.yml

env:
  WECOM_ROBOT: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
$:
  # Notify when an Issue is opened
  issue.open:
    - stages:
        - name: notice
          image: tencentcom/wecom-message
          settings:
            robot: $WECOM_ROBOT
            content: |
              > **New Issue Created**
              > **Title:** $CNB_ISSUE_TITLE
              > **Creator:** $CNB_ISSUE_OWNER
              > [View Details]($CNB_EVENT_URL)

  # Notify when an Issue is closed
  issue.close:
    - stages:
        - name: notice
          image: tencentcom/wecom-message
          settings:
            robot: $WECOM_ROBOT
            content: |
              > **$CNB_BUILD_USER closed an issue**
              > **Title:** $CNB_ISSUE_TITLE
              > [View Details]($CNB_EVENT_URL)

The pipeline triggerer is the user who created, closed, or reopened the Issue. The message format can be customized. For available variables, see Environment Variables.

Comment Count Limit

When the comment count of an Issue or PR exceeds 100, the corresponding issue.comment / pull_request.comment and @npc events will no longer trigger any pipeline.

---

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 creation	issue.comment@npc
Issue comment	issue.comment@npc
PR description creation	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	Pre-merged Commit
pull_request.update	Pre-merged Commit
pull_request.approved	Pre-merged Commit
pull_request.changes_requested	Pre-merged Commit
pull_request.comment	Pre-merged Commit (see note 3)
pull_request.comment@npc	Latest Commit of target branch (see note 4)
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 (see note 1)
web_trigger	Read config from branch/Tag (see note 2)
Scheduled Task	Latest Commit of specified branch
Rebuild	Current build Commit

Additional notes:

1. api_trigger: Version can be specified; cnb:apply is limited to current build Commit
2. web_trigger: Read configuration file from corresponding branch or Tag, refer to specific application scenarios
3. pull_request.comment: When the PR is already merged, uses the merged Commit (the source branch may have been deleted; no pre-merge is performed)
4. pull_request.comment@npc:
   • Cross-repo fork PR triggered by the PR author: uses the source repository's source branch code
   • PR already merged: uses the merged Commit (the source branch may have been deleted); git cherry-pick can sync commits to other branches

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.open: Issue created
• issue.reopen: Issue reopened
• issue.close: Issue closed
• issue.update: Issue content update (including title, description modification)
• issue.update.assignee_change: Issue assignee changed
• issue.update.priority_change: Issue priority changed
• issue.update.label_change: Issue label changed
• issue.comment: Issue comment
• issue.comment@npc: Triggered when @npc appears in Issue descriptions or comments

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

Issue and Comment Events:

Creating, closing, reopening, editing and commenting on an Issue require no write access to the repository, so the trigger may not be a repository member or administrator:

• Accessing the triggerer's resources leading to data leakage
• Tampering with the triggerer's 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:

• CNB_TOKEN Permission Restriction: The CNB_TOKEN built into the pipeline environment variables has strictly limited permissions to prevent unauthorized access
• CNB_TOKEN Resource Scope Restriction: The CNB_TOKEN for untrusted events is issued on behalf of the triggerer, who may not be a repository member. Its access scope is therefore restricted to the current repository by default and cannot access resources across repositories or root organizations, preventing repository configuration from being used to access the triggerer's resources in other repositories. To allow access across repositories within the root organization, a root organization administrator can enable the Allow untrusted events to operate across repositories switch under "Organization Settings → Cloud Native Build Control". Once enabled, the scope is restricted to the root organization (all repositories under it are accessible, but still not across root organizations). Forked repositories are excluded: a forked repository runs the .cnb.yml inherited from its upstream (authored by third parties), so its untrusted-event token is restricted to the current repository and is not opened up by this control. For NPC operations in cross-repo fork PRs, see the security restrictions of CNB_TOKEN. Code checkout uses a separate read-only token and is not affected by this restriction.
• 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