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:

.cnb.yml
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:

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

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

.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 (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.merged and push events 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:

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

Trigger Method: Only triggered by clicking the Auto Generate Tag button 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 with v, the auto-generated Tag will also include v, e.g., v4.1.9.
Custom Configuration: Users can override the default template by adding the following configuration to the root directory .cnb.yml file:

.cnb.yml
# 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_TAG

Note: 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_trigger 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 PR button 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 Review button 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.yml file:

In the following pipeline, the image plugin used is cnbcool/ai-review:latest, and parameters can be customized as needed.

.cnb.yml
# 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_IID

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

.cnb/settings.yml
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 Fang

For 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 path cnb/docs where the knowledge base role belongs, and the role name Yuan Fang is 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:
1. Load the .cnb.yml file from the default branch (e.g., main) of the repository where the knowledge base role belongs.
2. Parse the event configuration corresponding to the role name (e.g., Yuan Fang) from the configuration file.
3. If no event configuration is found under the role name, parse the default event configuration under $.
4. If no pipeline configuration is parsed from the knowledge base configuration file, use the system's default NPC event pipeline configuration.
Mentioning the System Role: Directly use the system's default NPC event pipeline configuration.

Knowledge Base Configuration Example:

.cnb.yml
.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: *npc

After 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_SLUG
CNB_NPC_NAME
CNB_NPC_PROMPT
CNB_NPC_AVATAR
CNB_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 push
pull_request.update: PR content update (including title, description modification)
pull_request.approved: PR approval granted
pull_request.changes_requested: PR review changes requested
pull_request.comment: PR comment
pull_request.comment@npc: Triggered when NPC is mentioned in a PR

Issue Related Events:

issue.comment: Issue comment
issue.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_events to 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