Configuring Schedule Triggers

The schedule trigger allows you to set the time when a build of the configuration will be run. The Builds Schedule section of the current Project Settings displays the configured build times. More than one schedule trigger can be added to a build configuration.

Triggering Conditions

The settings in this section define time and other conditions for automatic build triggering. You can schedule a recurring build or set a specific date and time for it.

Date and Time

In addition to triggering builds daily or weekly at a specified time for a particular time zone, you can specify advanced time settings using cron-like expressions. This format provides more flexible scheduling options.

TeamCity uses Quartz for working with cron expressions. See the examples below or consider using the CronMaker utility to generate expressions based on the Quartz cron format.

Examples

	Each 2 hours at :30	Every day at 11:45PM	Every Sunday at 1:00AM	Every last day of month at 10:00AM and 10:00PM
Seconds	0	0	0	0
Minutes	30	45	0	0
Hours	0/2	23	1	10,22
Day-of-month	*	*	?	L
Month	*	*	*	*
Day-of-week	?	?	1	?
Year(Optional)	*	*	*	*

Brief description of the cron format used

Cron expressions are comprised of six fields and one optional field separated with a white space. The fields are respectively described as follows:

Field Name	Values	Special Characters
Seconds	0-59	, - * /
Minutes	0-59	, - * /
Hours	0-23	, - * /
Day-of-month	1-31	, - * ? / L W
Month	1-12 of JAN-DEC	, - * /
Day-of-week	1-7 or SUN-SAT	, - * ? / L #
Year (Optional)	empty, 1970-2099	, - * /

For the description of the special characters, please refer to Quartz CronTrigger Tutorial.

VCS Changes

You can restrict a schedule trigger to start builds only if there are pending changes in your version control by enabling the Trigger only if there are pending changes option. This option considers only newly detected pending changes: if there were pending changes before the Trigger was created, the build is not triggered.

VCS Trigger Rules

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.

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 "-").

General Syntax

The general syntax for a single rule is:

+|-[:[user=VCS_username;][root=VCS_root_id;][comment=VCS_comment_regexp]]:Ant_like_wildcard

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.

Trigger Rules Examples

Example	Description
`+:.`	Includes all files
`-:**.html`	Excludes all `.html` files from triggering a build.
`-:user=techwriter;root=InternalSVN:/misc/doc/*.xml`	Excludes builds being triggered by `.xml` files checked in by the VCS 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 contains the word "minor" in the comment.
`-:comment=^oops$:**`	No triggering if the comment consists of the word "oops" only (according to Java Regular Expression principles `^` and `$` in pattern stand for string beginning and ending).

Build Changes

A schedule trigger can watch a build in any specified build configuration and trigger a build only if the watched build has changed since the previous triggering. You can select which build to watch:

Last finished build
Last successful build
Last pinned build
Last finished build with a specified build tag

If the Trigger detects a new build that satisfies the selected characteristic in the watched configuration, it queues a new build in own configuration.

The Trigger watches only regular (not personal or history) builds in the default branch.

If the triggered build depends on the watched build via a snapshot or artifact dependency, select the "Promote watched build" option so TeamCity can automatically promote the detected build to the triggered build. Otherwise, the build will be triggered as usual and will have no relation to the detected build.

Additional Options

Enforce Clean Checkout

Enable the Delete all files in the checkout directory before the build option to force TeamCity to clean all files in the checkout directory before running a build.
This option can also be applied to snapshot dependencies. In this case, all the builds of the build chain will be forced to use clean checkout. The option also enables rebuilding all dependencies (unless custom dependencies are provided via the custom build dialog or a schedule trigger promotes a build).

Trigger Build on All Enabled and Compatible Agents

Use this option to run a build simultaneously on all agents that are enabled and compatible with the build configuration. This option may be useful in the following cases:

run a build for agent maintenance purposes (for example, you can create a configuration to check whether agents function properly after an environment upgrade/update)
run a build on different platforms (for example, you can set up a configuration and specify for it a number of compatible build agents with different environments installed)

Build Queue Optimization Settings

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.

Branch Filter

By default, a schedule trigger works for all branches.

Trigger Rules and Branch Filter Combined

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 specified text and is also in a branch matched by the branch filter.