TeamCity 2019.2 Help

Snapshot Dependencies

By setting a snapshot dependency of a build (for example, build B) on other build's (build A's) sources, you can ensure that build B will start only after the one it depends on (build A) is run and finished. We call build A a dependency build, whereas build B is a dependent build.

The Dependencies page of the build configuration settings displays the configured dependencies and since TeamCity 2017.1, the Snapshot dependencies section of the page allows previewing the build chain and its configuration. The preview shows builds of the chain; the builds with automatic triggering configured are marked with this icon v.png.

When adding a new snapshot dependency, the following options need to be specified:

Option

Description

Depend on

Specify the build configuration for the current build configuration to depend on.

Enforce revisions synchronization

For all builds linked by snapshot dependencies with this option enabled, TeamCity will use the same sources snapshot (for example, the same revision for 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 a dependency build is promoted to the current build configuration, the build of the current build configuraiton 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).

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 the option is enabled, TeamCity will not run a dependency build, if another running or finished dependency build with the appropriate sources revision exists. See also Suitable Builds below. However, when a dependent build is triggered, the dependency build will also be put into the queue. Then, when the changes for the build chain are collected, this dependency build will be removed from the queue and the dependency will be set to a suitable finished build.

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 is failed, it will be re-run.

Run build on the same agent

When enabled, and B snapshot-depends on A, then builds of B are run on the same agent where the build of 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:

  • Run build, but add problem: the dependent build will be run and the problem will be added to it, changing its status to failed (if problem was not muted earlier)

  • Run build, but do not add problem: the dependent build will be run and no problems will be added

  • Make build failed to start: the dependent build will not run and will be marked as "Failed to start"

  • Cancel build: the dependent build will not run and will be marked as "Canceled".

Suitable Builds

A "suitable" build in terms of snapshot dependencies 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 selected.

For a build to be considered "suitable", it should comply with all of the conditions below:

  • use the same sources snapshot as the entire queued build chain being processed. If the build configurations have the same VCS settings, this basically means the one with the same sources revision. If the VCS settings are different (VCS roots or checkout rules), then "same sources snapshot" revisions means revisions taken simultaneously at some moment in time.

  • be successful (if "Only use successful builds from suitable ones" snapshot dependency option is set)

  • be a usual, not a personal build

  • have no customized parameters, also considering those set via reverse.dep. parameters (related feature request: TW-23700)

  • the original build should not be triggered selecting "rebuild" option for the dependency build configuration in question

  • have no VCS settings preventing effective revision calculation, see below

  • there is no other build configuration snapshot-depending on the current one with "Do not run new build if there is a suitable one" option set to "off"

  • the running build is not "hanging"

  • settings of the build configuration were 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.txt file in the hidden build's artifacts

  • if there is also an artifact dependency in addition to 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 reusing. These settings are:

  • Subversion: Checkout, but ignore changes mode

  • CVS: Checkout by tag mode

  • Perforce: Stream or Client connection settings, or label is specified in Label/revision to checkout option

  • Starteam: checkout mode option set to view label or promotion date


See also:

Concepts: Dependent Build