Trigger Rules
About 2073 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:
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_TOKENscoped 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/*matchesdev/featurebut notdev/team/feature.**matches any character including/. For example,dev/**matches bothdev/featureanddev/team/feature.
Use ** when branch names contain multiple / levels.
Common Matching Rules
.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_pipelineMatching 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:
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_BRANCHPull 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.updatebut notpull_request - PR creation, reopening, source branch push → triggers both
pull_requestandpull_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 | 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:
# 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_BRANCHauto_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.11type - If the latest Tag starts with
v, the automatically generated Tag will also havev, such asv4.1.9
Custom Configuration:
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_TAGConfiguration 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 pushpull_request.update: PR content update (including title, description modification)pull_request.approved: PR approval passedpull_request.changes_requested: PR approval rejectedpull_request.comment: PR commentpull_request.comment@npc: Triggered when@npcappears in PR descriptions or comments
Issue Related Events:
issue.comment: Issue commentissue.comment@npc: Triggered when@npcappears 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:
NPCconfiguration 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