Building Trigger Rules
About 1426 wordsAbout 5 min
Cloud Native Build
will fetch and parse the .cnb.yml
configuration file from the corresponding branch when an event is received. It retrieves the pipeline configuration for the corresponding event under that branch and then assigns a Runner to execute the build.
Take the push
event of the main
branch code as an example:
Code example:
# .cnb.yml
main: # Trigger branch
push: # Trigger event, corresponding to a build, can contain multiple Pipelines. It can be either an array or an object.
- stages: # Pipeline 1
- echo "do some job"
- stages: # Pipeline 2
- echo "do some job"
Trigger Branch
Corresponds to the branch of the code repository, used to match the branch corresponding to the event and specify the pipeline configuration.
Note: Configuring pipelines for other branches in .cnb.yml
under a certain branch does not mean that events from those branches will execute pipelines according to this configuration. Instead, it depends on the specific .cnb.yml
configuration under each branch.
Matching Patterns
Branch names support glob
pattern matching (What is 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 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_pipeline
Matching Strategy
Matching is done in stages, with priority. Only when there is no match result, the next stage will be attempted.
glob
matches branch names.$
fallback matches all branches not matched byglob
.
If multiple glob
rules match, all matched rules' pipelines will be executed in parallel.
Trigger Events
Specifies which event triggers the build. Supports configuring multiple pipelines for parallel execution.
Below is a list of events supported by Cloud Native Build
.
Branch Events
Events triggered by changes in remote code branches.
push
Triggered when a branch is pushed
.
commit.add
Triggered when there are new Commits
during a branch push
.
This event includes an additional environment variable CNB_NEW_COMMITS_COUNT
, which represents the number of new Commits
, with a maximum value of 99.
You can use git log -n
to view the newly added Commits
.
branch.create
Triggered when a branch is created
, and it also triggers the push
event.
branch.delete
Triggered when a branch is deleted
.
Pipeline configurations can be attached to the branch name
or $
.
The pipeline will use the configuration file of 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_BRANCH
Pull Request Events
Events triggered by Pull Request
related operations in remote code (hereinafter referred to as PR
).
pull_request
Triggered by PR
creation, reopening, and source branch push. The difference from pull_request.target
is explained in Code Version Selection.
pull_request.update
Triggered by PR
creation, reopening, source branch push, and PR
title or description changes.
pull_request
is a subset of pull_request.update
,i.e., changes to PR
title or description trigger pull_request.update
but not pull_request
.
PR
creation, reopening, and source branch push trigger both pull_request
and pull_request.update
.
pull_request.target
Triggered by PR
creation, reopening, and source branch push. The difference from pull_request
is explained in Code Version Selection.
pull_request.mergeable
Triggered when an open PR
meets the following conditions:
- The target branch is a protected branch and the following rules are checked:
- Requires reviewer approval.
- Needs to pass status checks (optional).
- Mergeable:
- No code conflicts.
- Status checks passed (if status checks are required and there are status checks).
- Review approved.
The configuration file for this event is taken from the target branch. Refer to Code Version Selection.
The pipeline will only execute if the target branch of the PR
has configured this event.
pull_request.merged
Triggered when a PR
is successfully merged.
Tips
Merging branch a
into branch b
triggers pull_request.merged
and push
events under branch b
.
pull_request.approved
Triggered when a user reviews a PR
and approves it.
Tips
If the protected branch requires multiple reviewers, a user's approval does not mean the PR
is in an approved state.
pull_request.changes_requested
Triggered when a user reviews a PR
and requests changes.
pull_request.comment
Triggered when a comment is created on a PR
.
Tag Events
Events triggered by Tag
related operations in remote code or the page.
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_BRANCH
auto_tag
Automatically generated Tag
event.
Trigger Method
Only triggered by clicking the
Auto Generate Tag
button on the repository'sTag
list page.Implementation Principle
Starts a pipeline, defaulting to the cnbcool/git-auto-tag plugin to automatically generate a
Tag
.Format Description
The
Tag
defaults to the3.8.11
format. If the latestTag
starts withv
, the automatically generatedTag
will also includev
, such asv4.1.9
.Custom
auto_tag
Event PipelineUsers can add the following configuration in the root directory
.cnb.yml
file to override the default template.# User-defined .cnb.yml configuration main: # Default branch, can be replaced with the actual default branch of the repository auto_tag: # Event name - stages: - name: auto tag image: "cnbcool/git-auto-tag:latest" settings: tagFormat: 'v\${version}' branch: $CNB_BRANCH repoUrlHttps: $CNB_REPO_URL_HTTPS exports: tag: NEW_TAG - name: show tag script: echo $NEW_TAG
tag_deploy.*
Events triggered by the Deploy
button on the repository Tag/Release
page.
Details refer to Deployment.
Issue Events
Events triggered by Issue
related operations.
Issue
event pipeline configurations need to be attached to $
.
issue.open
Triggered when an Issue
is created.
issue.close
Triggered when an Issue
is closed.
issue.reopen
Triggered when an Issue
is reopened.
api_trigger Custom Event
The event name is api_trigger
or starts with api_trigger_
, such as api_trigger_test
.
API custom events can be triggered in the following three ways:
- Triggered by cnb:apply.
- Triggered by cnb:trigger.
- Triggered by OPENAPI.
Methods 1 and 2 are encapsulations of method 3.
web_trigger Custom Event
The event name is web_trigger
or starts with web_trigger_
, such as web_trigger_test
.
Only triggered on the page.
Use cases:
- Can be combined with Deployment capabilities.
- Custom Buttons on the page.
Manually trigger builds (supports inputting environment variables, only triggers web_trigger
events).
Scheduled Task Events
Events triggered by scheduled tasks.
Details refer to Scheduled Tasks.
Workspace Events
Events triggered by clicking the Workspace
button on the page.
Details refer to Workspace.
Code Version Selection
When an event is triggered, the corresponding code version needs to be determined to fetch, parse the corresponding .cnb.yml
, and checkout the code to execute the pipeline. Usually, the code version aligns with intuition and the triggering branch, but for some events like PR
related or branch.delete
, additional considerations are made, and the code version may differ from the triggering branch.
Below is a list of how Cloud Native Build
selects the code version for each event:
- For
push
,commit.add
,branch.create
, andvscode
events, the latest commit of the current branch is selected. - For
auto_tag
,branch.delete
, andissue.*
events, the latest commit of the default branch is selected. - For
tag_push
andtag_deploy.*
events, the currentTag
is selected. - For
pull_request
,pull_request.update
,pull_request.approved
, andpull_request.changes_requested
events, which involve source and target branches, the pre-merged code version is selected. - For
pull_request.merged
events, the post-merged code version is selected. - For
pull_request.target
andpull_request.mergeable
events, the latest commit of the target branch before merging is selected. - For
api_trigger
custom events, the version can be specified. cnb:apply restricts it to the code version of the current pipeline. - For
web_trigger
custom events, the configuration file is read from the corresponding branch or Tag, depending on the specific use case. - For scheduled task events, the configuration file is read from the specified branch.
- For rebuilds, the code version of the current build is selected.