Snapshot Dependencies
By setting a snapshot dependency of a build (for example, build B) on another build's (build A) sources, you can ensure that build B will start only after build A is run and finished. We call build A a dependency build, whereas build B is a dependent build.
The Build Configuration Settings | Dependencies page displays the configured dependencies; the Snapshot Dependencies section of this page allows previewing the build chain and its configuration. The preview shows builds of the chain; the builds with configured automatic triggers are marked with 
icon.
A snapshot dependency has the following options:
Option | Description |
|---|---|
Depend on | Specify the build configuration to depend on. In our example, select build A as a dependency of the current build B. |
Enforce revisions synchronization | For all builds in a chain, which are linked by snapshot dependencies with this option enabled (by default), TeamCity will use the same sources' snapshot (for example, the same revision of the same VCS root). This is a recommended setting for configurations that need to use the same state of the sources to build successfully. If you disable this option for a snapshot dependency, then, when the dependency build is promoted to the current build configuration, the build of the current build configuration will use the most recent revision of the sources instead of the revision corresponding to the promoted dependency. This is useful when the builds do not have strict sources' dependencies (for example, as with package and deploy steps). In our example, if the snapshot dependency of build B has this option disabled, the behavior is following: Build A launches on revision 1.2 and, after finishing, is promoted to build B. TeamCity will find the latest revision for build B (let's say 1.3) at the moment of starting B. Note that the sources' snapshot rule is only applied to the parts of the builds chain) linked via the snapshot dependencies with the option enabled. |
Do not run new build if there is a suitable one | If this option is enabled, TeamCity will not run a new dependency build, if another running or finished dependency build with the appropriate sources' revision already exists. See also Suitable Builds. |
Only use successful builds from suitable ones | A new triggered build will only use successfully finished suitable builds as dependencies. If the latest finished suitable build fails, it will be rerun. |
Run build on the same agent | When enabled and B snapshot-depends on A, each build B is run on the same agent where build A from the same build chain was run. |
On failed dependency/ On failed to start/canceled dependency | If a dependency fails, you can manage the status of the dependent build by selecting one of the following options:
|
Suitable Builds
In terms of snapshot dependencies, a suitable build is a build which can be used instead a queued dependency build within a build chain. That is, a queued build which is a part of a build chain can be dropped — and the builds depending on it can be made dependent on another queued, running, or already finished "suitable" build. This behavior only works when the "Do not run new build if there is a suitable one" option of a corresponding snapshot dependency is enabled.
For a build to be considered "suitable", it should comply with all these conditions:
It must use the same sources' snapshot as the entire queued build chain being processed. If the build configurations have the same VCS settings, this means the same sources' revision. If the VCS settings are different (VCS roots or checkout rules), this means the revisions taken simultaneously at some moment in time.
It must be successful (if the "Only use successful builds from suitable ones" snapshot dependency option is enabled).
It must be a usual, not a personal build.
It must have no customized parameters, including those set via
reverse.dep.parameters (related feature request: TW-23700 ).The original build must not be triggered by the "Rebuild" action for the dependency build configuration.
It must have no VCS settings preventing effective revision calculation, see more details.
There is no other build configuration snapshot-depending on the current one with the disabled "Do not run new build if there is a suitable one" option.
The running build is not "hanging".
The settings of the build configuration have not changed since the build (that is, the build was run with the current build configuration settings). This also includes no changes to the parameters of all the parent projects of the build configuration. You can check if the settings were changed between several builds by comparing
.teamcity/settings/digest.txtfile in the hidden build's artifacts.If there is also an artifact dependency in addition to the snapshot one, the suitable build should have artifacts.
All the dependency builds (the builds the current one depends on) are "suitable" and are appropriately merged.
VCS Settings Disabling Builds Reuse
Some settings in VCS roots can effectively disable builds reuse. These settings are:
Subversion: Checkout, but ignore changes mode
CVS: Checkout by tag mode
Perforce: Stream or Client connection settings, or label is specified as the Label/revision to checkout
Starteam: checkout mode option set to view label or promotion date