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) | * | * | * | * |
See also other examples.
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_wildcardtip
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/pathfromsome_userwill be included unless you add a specific exclusion rule for this user and this path at once, like-:user=some_user:/some/path/**
Trigger Rules Examples
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 "minor" in the comment. |
-:comment=^oops$:** | No triggering if the comment consists of the word "oops" only (according to Java Regular Expression principles |
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.
Read more in Branch Filter.
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.