Configuring VCS Triggers

{toc}
VCS triggers automatically start a new build each time TeamCity detects new changes in the configured VCS roots.

TeamCity periodically (according to root's Changes Checking Interval of a VCS root) polls VCS roots of the build configuration for changes. Newly detected changes appear as Pending Changes of a build configuration.
{hidden-data}note: too trivial to write this
You can add simple VCS trigger, which will start a build each time the changes are detected by clicking *Add new trigger*, choosing *VCS Trigger* and clicking *Save*.
{hidden-data}
A new VCS trigger with default settings triggers a build each time new changes are detected.

However you can adjust a VCS trigger to your needs by means of [Quiet Period Settings|#quietPeriod] and [Build Trigger Rules|#buildTriggerRules].

h3. Trigger on changes in snapshot dependencies

By default, If you have a build chain (i.e. a number of build configurations interconnected by snapshot dependencies), automatic triggering of builds is performed in one direction only: if the first build in chain is triggered, all the builds it depends on are triggered too, but *not vice versa*. ([Learn more about snapshot dependencies|Dependent Build]) Use this option to change this behaviour.
For example, build A snapshot-depends on B: A--->B. When build A is triggered, build B is triggered too. But if build B is triggered, nothing happens to build A. If you want build A to be triggered on changes in B, enable this option. See also an example at [Build Dependencies|Build Dependencies Setup#triggerOnChanges] page.

{anchor:per-check-in}
h3. Per-check-in Triggering

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. Moreover, 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 in sorting out whose change has broken a build, or caused new test failure.

{anchor:quietPeriod}

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

*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 actual quiet period will not be less than maximum checking for changes interval among build configuration VCS roots. Because TeamCity must ensure that changes were collected at least once during the quiet period.

Quiet period can be set to the default value (which can be changed globally at the *Administration* \| *Global Settings* page), or custom value can be specified.
{note}Note, that when a build is triggered by a trigger with 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].
{note}{anchor:buildTriggerRules}

Each rule is ether an "include" (starts with "+") or an "exclude" (starts with "-").

The general syntax for a single rule is:
{code}
+|-:[user=VCS_username;][root=VCS_root_name;][comment=VCS_comment_regexp]:Ant_like_wildcard
{code}
Where:
- *Ant_like_wildcard* \- A [wildcard|Wildcards] to match the changed file path. Only "\*" and "\*\*" patterns are supported, "?" pattern is *not* supported. The file paths in the rule can be relative (resulting paths on the agent will be matched) or absolute (started with '/', VCS paths relative to VCS root are matched).
- *VCS_username* \- if specified, limits the rule only to the changes made by a user with corresponding VCS username.
- *VCS_root_name* \- 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 VCS comment. Use [Java Regular Expression|http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html] pattern for matching text in a comment (see examples below).

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 rules.
{info}When entering rules please note that as soon as you enter any "\+" rule, TeamCity will remove the default "include all" setting. To include all the files, use "\+:." rule.
{info}

h4. Trigger Rules Example

{code}
+:.
-:**.html
-:user=techwriter;root=Internal SVN:/misc/doc/*.xml
-:lib/**
-:comment=minor:**
-:comment=^minor$:**
{code}
Here,
- "{{\-:**.html}}" excludes all {{.html}} files from triggering a build.
- "{{\-:user=techwriter;root=Internal SVN:/misc/doc/*.xml}}" excludes builds being triggered by {{.xml}} files checked in by user "techwriter" to the {{misc/doc}} directory 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|http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html] principles ^ and $ in pattern stand for string beginning and ending)
{excerpt}