Configuring Maven Triggers
The Triggers page of Build Configuration Settings allows you to add the following Maven-related triggers:
Checksum Based Triggering
The trigger checks if the content of the dependency has actually changed by verifying its checksum from the repository against the locally stored version. Before triggering a build, TeamCity tries to determine the checksum of the required dependency by downloading the file digest (MD5/SHA-1) associated with that artifact.
If the checksum can be retrieved, and it matches a locally stored one, no build is triggered. If the checksum is different, a build is triggered.
If the checksum cannot be retrieved from the remote server, the dependency will be downloaded, TeamCity will calculate its checksum and follow the build triggering mechanism described above.
Maven Snapshot Dependency Trigger
Maven snapshot dependency trigger adds a new build to the queue when there is a real modification of the snapshot dependency content in the remote repository which is detected by the checksum change.
Dependency artifacts are resolved according to the POM and the server-side Maven Settings.
note
Note that since Maven deploys artifacts to remote repositories sequentially during a build, not all artifacts may be up-to-date at the moment the snapshot dependency trigger detects the first updated artifact. To avoid inconsistency, select the Do not trigger a build if currently running builds can produce snapshot dependencies check box when adding this trigger, which will ensure the build won't start while builds producing snapshot dependencies are still running.
note
Simultaneous usage of snapshot dependency and dependency trigger for a build Assume build A depends on build B by both snapshot and trigger dependency. Then, after the build B finishes, build A will be added into the queue, only if build B is not a part of the build chain containing A.
Maven Artifact Dependency Trigger
Maven artifact dependency trigger adds build to the queue when there is a real modification of the dependency content which is detected by the checksum change.
To add a trigger, specify the following parameters in the Add New Trigger dialog:
Parameter | Description |
|---|---|
Group ID | Specify an identifier of a group the desired Maven artifact belongs to. |
Artifact ID | Specify the artifact's identifier. |
Version or Version range | Specify a version or version range of the artifact. The version range syntax is described in the section below. SNAPSHOT versions can also be used. |
Type | Define explicitly the type of the specified artifact. By default, the type is |
Classifier | (Optional) Specify the classifier of an artifact. |
Maven repository URL | Specify a URL to the Maven repository. Note that this parameter is optional. If the URL is not specified, then:
|
Do not trigger a build if currently running builds can produce this artifact | Select this option to trigger a build only after the build that produces artifacts used here is finished. |
Advanced Options
Parameter | Description |
|---|---|
Repository ID | Allows using authorization from the effective Maven settings |
User settings selection | Allows selecting effective settings. The same as User Settings of the Maven runner. |
TeamCity determines the effective repository to be checked for the artifact updates and to trigger builds if changes are detected as follows:
if a URL and Repository ID are set, authentication will be chosen from the effective settings (see below)
if only a URL is set, the old behavior is preserved: a temporary repository ID is used (
_tc_temp_remote_repo)if URL is not set (regardless of the Repository ID), the artifact will be looked up in a repository available according to the effective settings.
TeamCity determines effective settings as follows:
in the trigger settings a user can choose among the default, custom or uploaded Maven settings. See Maven Server-Side Settings for details.
if no specific settings are configured for the trigger, Maven build step settings are used
if no settings for the trigger are configured and there are no Maven build steps, the
defaultserver Maven settings will be used.
Version Ranges
For specifying version ranges use the following syntax, as proposed in the Maven documentation.
Note that Maven Artifact Dependency Trigger can be used not only for fixed-version artifacts but also for snapshots as a fine-grained alternative to the Maven Snapshots Dependency Trigger.
Range | Meaning |
|---|---|
| x <= 1.0 |
| "Soft" requirement on 1.0 (just a recommendation — helps select the correct version if it matches all ranges) |
| Hard requirement on 1.0 |
| 1.2 <= x <= 1.3 |
| 1.0 <= x < 2.0 |
| x >= 1.5 |
| x <= 1.0 or x >= 1.2. Multiple sets are comma-separated |
| This excludes 1.1, if it is known not to work in combination with this library |
1.0-SNAPSHOT | The trigger will check the latest snapshot version for updates |
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.
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.