Configuring VCS Triggers
VCS triggers automatically start a new build each time TeamCity detects new changes in the configured VCS roots.
A new VCS trigger with the default settings triggers a build each time new changes are detected: the version control is polled for changes according to the Configuring VCS Roots of a VCS root. Newly detected changes appear as Pending Changes of a build configuration. If several check-ins are made during this time, only one build will be triggered. If you have several VCS roots attached to a build configuration, TeamCity will add the build to the queue only after the longest of the specified intervals.
After the last change is detected, there is a quietPeriod before the build is started.
The global default value for both options is 60 seconds and can be configured for the server on the Administration | Global Settings page.
You can adjust a VCS trigger to your needs using the options described below:
Trigger a build on changes in snapshot dependencies
If you have a build chain (i.e. a number of builds interconnected by snapshot dependencies), the triggers are to be configured in the resulting build, the top-most build. When this build is triggered, all its snapshot dependencies are triggered too.
If you use different VCS settings in the builds of a chain you might benefit from enabling the Trigger a build on changes in snapshot dependencies VCS trigger option.
For example, the Test build configuration snapshot-depends on the Compile build configuration. When a Test build is triggered, a Compile build is triggered too. But if Compile is triggered, nothing happens to Test. If you want a Test build to be triggered on changes in Compile, enable Trigger a build on changes in snapshot dependencies in the VCS Trigger options of the Test build configuration. In this setup, no VCS trigger is required for the Compile Build configuration.
If triggering rules are specified (described below), they are applied to all the changes (including changes from snapshot dependencies) and only the changes matching the rules trigger the build chain.
See also an example at the Build Dependencies page.
Per-check-in Triggering
When this option is not enabled, several check-ins by different committers can be made; and once they are detected, TeamCity will add only one build to the queue with all of these changes.
If you have fast builds and enough build agents, you can make TeamCity launch a new build for each check-in ensuring that no other changes get into the same build. To do that, select the Trigger a build on each check-in option. If you select the Include several check-ins in build if they are from the same committer option, and TeamCity will detect a number of pending changes, it will group them by user and start builds having single user changes only.
This helps to figure out whose change broke a build or caused a new test failure, should such issue arise.
Quiet Period Settings
By specifying the quiet period you can ensure the build is not triggered in the middle of non-atomic check-ins consisting of several VCS check-ins.
A quiet period is a period (in seconds) that TeamCity maintains between the moment the last VCS change is detected and a build is added into the queue. If new VCS change is detected in the Build Configuration within the period, the period starts over from the new change detection time. The build is added into the queue only if there were no new VCS changes detected within the quiet period. Note that the actual quiet period will not be less than the maximum checking for changes interval among the VCS roots of a build configuration, as TeamCity must ensure that changes were collected at least once during the quiet period.
The quiet period can be set to the default value (60 seconds, can be changed globally at the Administration | Global Settings page) or to a custom value for a build configuration.
VCS Trigger Rules
If no trigger rules specified, a build is triggered upon any detected change displayed for the build configuration. You can affect the changes detected by changing the VCS root settings and specifying Checkout Rules.
To limit the changes that trigger the build, use the VCS trigger rules. You can add these rules manually in the text area (one per line), or use the Add new rule option to generate them.
Each rule is ether an "include" (starts with "+") or an "exclude" (starts with "-").
The general syntax for a single rule is:
Where:
Ant_like_wildcard - A wildcard to match the changed file path. Only "*" and "**" patterns are supported,the "?" pattern is not supported. The file paths in the rule can be relative (not started with '/' or '\') to match resulting paths on the agent or absolute (started with '/') to match VCS paths relative to a VCS root. For each file in a change the most specific rule is found (the rule matching the longest file path). The build is triggered if there is at least one file with a matching "include" rule or a file with no matching "exclude" rules.
Managing Users and User Groups- if specified, limits the rule only to the changes made by a user with the corresponding VCS username.
VCS_root_id - if specified, limits the rule only to the changes from the corresponding VCS root.
VCS_comment_regexp - if specified, limits the rule only to the changes that contain specified text in the VCS comment. Use the Java Regular Expression pattern for matching the text in a comment (see examples below). The rule matches if the comment text contains a matched text portion; to match the entire text, include the ^ and $ special characters.
Trigger Rules Example
Here,
"
-:**.html" excludes all.htmlfiles from triggering a build."
-:user=techwriter;root=InternalSVN:/misc/doc/*.xml" excludes builds being triggered by.xmlfiles checked in by the VCS user "techwriter" to themisc/docdirectory of the VCS root named Internal SVN (as defined in the VCS Settings). Note that the path is absolute (starts with "/"), thus the file path is matched from the VCS root."
-:lib/**" prevents the build from triggering by updates to the "lib" directory of the build sources (as it appears on the agent). Note that the path is relative, so all files placed into the directory (by processing VCS root checkout rules) will not cause the build to be triggered."
-:comment=minor:**" prevents the build from triggering, if the changes check in comment contains word "minor"."
-:comment=^oops$:**" no triggering if the comment consists of the only word "oops" (according to Java Regular Expression principles ^ and $ in pattern stand for string beginning and ending)
Branch Filter
When a VCS Root has branches configured, the Branch filter setting appears in the trigger options. The branch filter limits the set of logical branch names according to specified rules and has the following format:
Where logical branch name is a part of branch name matched by branch specification (i.e. displayed for a build in TeamCity UI), see Working With Feature Branches. Wildcard character ('*') can also be used.
By default, the branch filter is set to accept all branches (+:*), which is also the equivalent of the empty branch filter.
Examples: Only default branch is accepted:
All branches except default are accepted:
Only branches with with feature- prefix are accepted:
Triggering a Build on Branch Merge
The VCS trigger is fully aware of branches and will trigger a build once a check-in is detected in a branch.
When changes are merged / fast-forwarded from one branch to another, strictly speaking there are no actual changes in the code. By default, the VCS trigger behaves in the following way:
When merging/fast forwarding of two non-default branches: the changes in a build are calculated with regard to previous builds in the same branch, so if there is a build on same commit in a different branch, the trigger will start a build in another branch pointing to the same commit.
If the default branch is one of the branches in the merging/fast-forwarding, the changes are always calculated against the default branch, if there is a build on same revision in the default branch, TeamCity will not run a new build on the same revision.