Configuring Schedule Triggers

The schedule trigger allows defining a schedule for automatically running builds in a given configuration. Multiple schedule triggers can be added to a single build configuration.

The Builds Schedule section of the current Project Settings displays the configured build times.

Triggering Conditions

This section describes the schedule trigger's parameters such as timing and VCS rules.

Date and Time

You can schedule a recurring build or set a specific date and time for it.

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 these examples or consider using the CronMaker utility to generate expressions based on the Quartz cron format.

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.

If the " Show changes from snapshot dependencies " option is enabled in the build configuration Version Control Settings, a schedule trigger will also consider changes from dependency configurations).

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

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 `oops` word only (according to Java Regular Expression principles `^` and `$` in the pattern stand for string beginning and ending).
+:comment=#teamcity:**	Triggers the build if the comment contains the `#teamcity` keyword.
+:comment=(?s)#teamcity.#major:*	Triggers the build if the comment contains both `#teamcity` and `#major` keywords. Here, `(?s)` is a DOTALL pattern that makes the character `.` match any character, including a line terminator, and allows checking multiline comments. For example, the following comment will trigger the build: #teamcity the first line #major the second line

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 its own configuration.

The trigger watches only regular (not personal or history) builds in the target branch. If the watched configuration has finished builds in multiple branches, the trigger settings also include the Build branch filter field that allows you to watch builds in the specific branch only. This setting is initially set to +:<default>, which means the trigger will monitor builds only in the default branch of the watched configuration.

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.

Triggered Build Customization

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.

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.

Last modified: 18 September 2024