Configuring VCS Triggers
VCS triggers automatically start a new build each time TeamCity detects new changes in the configured VCS roots and displays the change in the pending changes. Multiple VCS triggers can be added to a build configuration.
A new VCS trigger with the default settings triggers a build once there are pending changes in the build configuration: the version control is polled for changes according to the checking for changes interval of a VCS root honoring a VCS commit hook if configured. Only the changes matched by the checkout rules are displayed as pending and thus are processed by the trigger. If several check-ins are made within short time frame and discovered by TeamCity together, only one build will be triggered.
After the last change is detected, a quiet period can be configured to wait for some time without changes before the build is queued.
The global default value for both options is 60 seconds and can be configured for the server on the Administration | Global Settings page.
warning
If your build configuration targets a repository where non-trusted users can push commits or create pull (merge) requests, do not configure VCS triggers and/or Pull Requests build features that automatically run builds with these changes. Instead, start new builds manually after you inspect and verify incoming changes. Otherwise, TeamCity can execute malicious code introduced in these changes (for example, handle a service message sent from the source code or apply altered project settings from modified project settings directory files).
See this section for more information about potential damage caused by users who can modify repository code: Security Notes.
If you have a build chain (that is a number of builds interconnected by snapshot dependencies), the triggers are to be configured in the final build in the chain. This is pack setup in the image below.
The VCS build trigger has another option that alters triggering behavior for a build chain. With this options enabled, the whole build chain will be triggered even if changes are detected in dependencies, not in the final build.
Let's take a build chain from the example: pack setup
— depends on — tests
— depends on — compile
.
With the VCS Trigger set up in the pack setup
configuration, the whole build chain is usually triggered when TeamCity detects changes in pack setup
; changes in compile
will trigger compile
only and not the whole chain. If you want the whole chain to be triggered on a VCS change in compile
, add a VCS trigger with the " Trigger on changes in snapshot dependencies " option enabled to the final build configuration of the chain, pack setup
. This will not change the order in which builds are executed, but will only trigger the whole build chain, if there is a change in any of snapshot dependencies. In this setup, no VCS triggers are required for the compile
or tests
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 details at the Build Dependencies page.
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 a 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.
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 a 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.
note
Note that when a build is triggered by a trigger with the VCS quiet period set, the build is put into the queue with fixed VCS revisions. This ensures the build will be started with only the specific changes included. Under certain circumstances this build can later become a History Build.
By default, TeamCity optimizes the build queue: already queued build can be replaced with an already started build or a more recent queued build. You can disable this default behavior by unchecking the corresponding box.
If no trigger rules are specified, a build is triggered upon any change detected for the build configuration. You can control what changes are detected by changing the VCS root settings and specifying checkout rules.
tip
Watch our video guide on the difference between the checkout and trigger 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 button to generate them (if necessary, scroll down to reveal the button).
Each rule is ether an "include" (starts with +
) or an "exclude" (starts with -
).
The general syntax for a single rule is:
+|-[:[user=VCS_username;][root=VCS_root_id;][comment=VCS_comment_regexp]]:Ant_like_wildcard
tip
Here, the pipe symbol
|
represents the OR command, as in regular expressions: use+
for including, OR-
for excluding.
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.VCS_username
: 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.
tip
When specifying the rules, note that as soon as you enter any
+
rule, TeamCity will change the implicit default from "include all" to "exclude all".
To include all the files, use+:.
rule.Also, rules are sorted according to path specificity. If you have an explicit inclusion rule for
/some/path
, and exclusion rule-:user=some_user:.
for all paths, commits to the/some/path
fromsome_user
will be included unless you add a specific exclusion rule for this user and this path at once, like-:user=some_user:/some/path/**
Example | Description |
---|---|
+:. | Includes all files |
-:**.html | Excludes all |
-:user=techwriter;root=InternalSVN:/misc/doc/*.xml | Excludes builds being triggered by |
-:lib/** | Prevents the build from triggering by updates to the |
-:comment=minor:** | Prevents the build from triggering, if the changes check contains the word |
-:comment=^oops$:** | No triggering if the comment consists of the |
+:comment=#teamcity:** | Triggers the build if the comment contains the |
+:comment=(?s)#teamcity.*#major:** | Triggers the build if the comment contains both For example, the following comment will trigger the build:
|
Read more in Branch Filter.
Trigger rules and branch filter are combined by AND, which means that the build is triggered only when both conditions are satisfied.
For example, if you specify a comment text in the trigger rules field and provide the branch specification, the build will be triggered only if a commit has the special text and is also in a branch matched by branch filter.
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.
The Build Customization tab of a trigger's settings allows configuring custom parameters of builds started by this trigger. Similarly to the Run Custom Build dialog, it lets you override values of build parameters and choose if the checkout directory should be cleaned before the build.
On this tab, you can customize the value of any parameter used in the current build configuration. Or, you can add a new parameter, and it will be available only in builds started by this trigger. If the current build has snapshot dependencies on other builds, such a parameter can also be used to override a certain property of a dependency build configuration: use the reverse.dep.<dependencyBuildID>.<property>
syntax for this.
tip
This functionality gets more effective if you combine it with the build step execution conditions. You just need to add a parameter-based condition to a step and then configure two triggers: one will run builds with this step (when the condition is satisfied) and one — without it. A popular use case is to run a limited number of tests in regular builds but a full set of tests in a nightly build, when the server load is the lowest.
Note that if you redefine a build parameter inside a trigger and then delete the original parameter in Parameters, its redefined value will be converted to the trigger's own plain-text parameter. This is crucial to consider when customizing secure values, as they are only concealed if stored with the "Password" type and will become readable if converted to plain text.
TeamCity allows solving similar tasks in multiple ways, and in some cases it is still preferable to create different build configurations. For example, if there are too many custom runs in the same configuration, it might be harder for TeamCity to predict the exact duration of each build. If you need to trigger builds with numerous different parameters, we suggest that you create a build configuration template and use it as a blueprint for several configurations, each with its own parameters.
Thanks for your feedback!