Trigger Rules
About 2677 wordsAbout 9 min
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:
- Git Operation Events: Code push, branch creation, PR operations, etc.
- Page Operation Events: Manual triggers, button clicks, AI function operations, etc.
- API Request Events: Triggered via OPENAPI or built-in tasks
- Scheduled Task Events: Triggered according to a predefined schedule
- 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:
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_pipelineMatching Strategy
The system matches branches in stages by priority, proceeding to the next stage only if the previous one finds no match:
- Glob Pattern Matching: Attempts to match the branch name against all glob rules.
- 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
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_BRANCHPull 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:
- The target branch is a protected branch with the following rules enabled:
- Requires reviewer approval
- Requires status checks to pass (optional)
- Is mergeable
- No code conflicts
- Status checks pass (if required and status checks exist)
- 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.mergedandpushevents 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_BRANCHauto_tag: Auto-generate Tag event.
- Trigger Method: Only triggered by clicking the
Auto Generate Tagbutton on the repository's Tag list page. - Implementation Principle: Launches a pipeline, defaulting to using the cnbcool/git-auto-tag plugin to automatically generate the Tag.
- Format Description: The Tag defaults to a format like
3.8.11. If the latest Tag starts withv, the auto-generated Tag will also includev, e.g.,v4.1.9. - Custom Configuration: Users can override the default template by adding the following configuration to the root directory
.cnb.ymlfile:
# 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_TAGNote: 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_triggerevents).
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.
- Trigger Method: Only triggered by clicking the
AI Auto-Submit PRbutton on the repository's Issue details page. - 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.
- Trigger Method: Only triggered by clicking the
AI Reviewbutton on the repository's PR details page. - 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.
- Custom Configuration: Users can override the default template by adding the following configuration to the root directory
.cnb.ymlfile:
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_IIDWorkspace 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:
- Triggered by cnb:apply
- Triggered by cnb:trigger
- 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.
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.
NPC Events
When an AI role from the knowledge base or the system role CodeBuddy is mentioned (@) in an Issue or Pull Request (PR) comment, an NPC event will be triggered.
Example
In the .cnb/settings.yml file of the cnb/docs repository, you can define knowledge base roles. For example:
knowledgeBase:
button:
name: "Knowledge Base"
description: "Description of the knowledge base"
roles:
- name: Yuan Fang
prompt: |
You refer to yourself as "Yuan Fang" and address the user as "My Lord."
Your catchphrase is "There must be something fishy about this!"
Before ending the conversation, politely reply with: "There must be a huge secret behind this.\n."
In the last line, you will output a sticker.
Whether in daily conversations or explaining knowledge, you will maintain the above style.
Use the Chinese character 『~』 to replace all English '~'.
Answer the following questions in a humble tone.
defaultRole: Yuan FangFor detailed configuration of the knowledge base, please refer to the UI Customization Configuration File.
Trigger Method
In an Issue or PR comment, mention the knowledge base role or system role using @ to trigger an NPC event. For example:
Mentioning a Knowledge Base Role:
@cnb/docs(Yuan Fang) Please help me with this issue.Here,
@is followed by the repository pathcnb/docswhere the knowledge base role belongs, and the role nameYuan Fangis enclosed in parentheses.Mentioning the System Role:
@CodeBuddy Please help me with this issue.
Triggered Events
Based on the triggering scenario, the following NPC events will be triggered:
- issue.comment@npc: Triggered when an NPC is mentioned in an Issue comment.
- pull_request.comment@npc: Triggered when an NPC is mentioned in a PR comment.
Execution Process
CNB will parse the pipeline configuration according to the following steps:
Mentioning a Knowledge Base Role:
- Load the
.cnb.ymlfile from the default branch (e.g.,main) of the repository where the knowledge base role belongs. - Parse the event configuration corresponding to the
role name(e.g.,Yuan Fang) from the configuration file. - If no event configuration is found under the
role name, parse the default event configuration under$. - If no pipeline configuration is parsed from the knowledge base configuration file, use the system's default NPC event pipeline configuration.
- Load the
Mentioning the System Role: Directly use the system's default NPC event pipeline configuration.
Knowledge Base Configuration Example:
.npc: &npc
- stages:
- name: echo extra env
script: |
echo $CNB_NPC_SLUG
echo $CNB_NPC_NAME
echo $CNB_NPC_PROMPT
echo $CNB_NPC_AVATAR
echo $CNB_NPC_ENABLE_THINKING
# NPC events can be matched under the role name
"Yuan Fang":
issue.comment@npc: *npc
pull_request.comment@npc: *npc
# If no NPC event is defined under the role name, parse under $.
$:
issue.comment@npc: *npc
pull_request.comment@npc: *npcAfter the NPC pipeline configuration is loaded and parsed, it will be executed on the default branch of the repository to which the comment belongs, with the commenter as the trigger.
Environment Variables
When the NPC event pipeline is executed, the following additional environment variables will be added:
CNB_NPC_SLUGCNB_NPC_NAMECNB_NPC_PROMPTCNB_NPC_AVATARCNB_NPC_ENABLE_THINKING
For detailed descriptions of these environment variables, please refer to the Default Environment Variables.
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:
- push, commit.add, branch.create, vscode events: Select the latest Commit of the current branch.
- auto_tag, branch.delete, issue.* events: Select the latest Commit of the default branch.
- tag_push, tag_deploy.* events: Select the current Tag.
- pull_request, pull_request.update, pull_request.approved, pull_request.changes_requested、pull_request.comment events: Take the pre-merged Commit.
- pull_request.merged event: Take the post-merge Commit.
- pull_request.target, pull_request.mergeable events: Take the latest Commit of the target branch before merging.
- api_trigger custom events: Can specify a version. cnb:apply is restricted to the current build's Commit.
- web_trigger custom events: Read the configuration file from the corresponding branch/Tag, refer to the specific use case.
- Scheduled task events: Read the configuration file from the latest Commit of the specified branch.
- Rebuild: Take the current build's Commit.
Untrusted Events
Untrusted events are event types where the code source or trigger cannot be fully controlled.
Event List
The following events are considered untrusted:
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 grantedpull_request.changes_requested: PR review changes requestedpull_request.comment: PR commentpull_request.comment@npc: Triggered when NPC is mentioned in a PR
Issue Related Events:
issue.comment: Issue commentissue.comment@npc: NPC trigger in Issue
Risk Scenarios
PR Events: Pipeline configuration originates from the source branch and may be modified by unauthorized users, posing the following risks:
- Malicious code injection or sensitive code leakage
- Tampering with build artifacts (e.g., images, binary files)
- Key or credential leakage through referencing key repository files
Comment Events: The trigger is the commenter, who may not be a repository member or administrator:
- Data leakage through accessing commenter's resources
- Damage caused by tampering with commenter's resources
NPC Events: The pipeline is provided by the NPC's repository, with the trigger being the commenter, creating compounded risks:
- NPC configuration source is uncontrollable and may be maliciously tampered with
- Both commenter resource leakage and tampering risks exist simultaneously
Security Measures
To mitigate the above risks, the system implements the following protection mechanisms for untrusted events:
CNB_TOKEN Permission Restriction: The built-in CNB_TOKEN in pipeline environment variables is strictly limited to prevent unauthorized access
Explicit File Reference Declaration: When pipelines for untrusted events reference external files, the referenced files must explicitly declare
allow_eventsto specify which events are allowed to reference them, preventing sensitive files from being accidentally referenced
Usage Recommendations
- Choose Trusted NPCs: Prioritize selecting NPC roles provided by trusted repositories when commenting
- Sensitive Task Isolation: For tasks involving key operations, sensitive data processing, or other critical content, it is recommended to execute them in trusted events such as push or merge