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.
This section describes the schedule trigger's parameters such as timing and VCS rules.
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.
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).
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_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/**
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: |
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.
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).
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)
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.
By default, a schedule trigger works for all branches.
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 specified text and is also in a branch matched by the branch filter.
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.