Trigger Rules

About 2178 wordsAbout 7 min

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:
        - echo "do some job"
    - stages:
        - 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.

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
"dev/*": # Match branches starting with dev/ (no multi-level /)
  push:
    - stages:
        - name: do something
          script: echo "dev branch"

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

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

"**": # Match all branches
  push:
    - stages:
        - name: do something
          script: echo "all branches"

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.

pull_request.mergeable Trigger Conditions

Triggered when an open PR simultaneously meets the following conditions:

Target branch is a protected branch, with the following rules checked:
- Requires reviewer approval
- Requires passing status checks (optional)
Mergeable:
- No code conflicts
- Status checks passed (if "requires passing status checks" is checked and there are status checks)
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	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.

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

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
pull_request.comment@npc	Latest Commit of target branch
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:

api_trigger: Version can be specified; cnb:apply is limited to current build Commit
web_trigger: Read configuration file from corresponding branch or Tag, refer to specific application scenarios

Note

For pull_request.comment@npc events in cross-repo fork PRs, if the trigger is the PR author, the source repository's source branch code is used.

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

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:

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