Dependent Build

Snapshot Dependency

Snapshot Dependency is a powerful concept that allows expressing source-level dependencies between build configurations in TeamCity. The primary goal is to allow complex build procedures via creating different build configurations linked with snapshot dependencies. This, in particular, allows dividing a single monolith build into a set of interlinked builds (Build Chain) with flexible reuse rules. TeamCity follows the declarative style of defining the build structure on this level (declaring dependencies rather than adding build triggers) as it allows for more flexible and powerful features.

See Build Dependencies Setup for a description of typical snapshot dependencies usages and related blog posts: September 2019, March 2016, April 2012.

A snapshot dependency of build configuration A on build configuration B ensures that each build of A has a "suitable" build of B before build of A can start. Both builds of A and B use the same sources snapshot (revision of the sources being the same or taken at the same time if the VCS roots are different) when they belong to the same chain and when revisions synchronization is enforced. If revisions synchronization is not enforced, then build A can use up-to-date revisions when promoting a finished build B to A (read more in Build Chain).

The build results page of a build with snapshot dependencies allows reviewing all the dependency builds and their errors, if there are any.

A snapshot dependency alters the builds' behavior in the following way:

• when a build is queued, so are the builds from all the build configurations it snapshot-depends on, transitively; TeamCity then determines the revisions to be used by the builds ("checking for changes" process).

• if some build configurations already have started builds with matching changes ("suitable builds") and the snapshot dependency has the "Do not run new build if there is a suitable one" option ON, TeamCity optimizes the queued builds by using an already finished builds instead of the queued ones. Corresponding queued builds are then silently removed. This procedure can be performed several times, because, while builds of the chain remain in the queue, new builds may start and finish;

• all builds linked via snapshot dependencies are started by TeamCity with explicit specification of the sources' revision. The revision is calculated so that it corresponds to the same moment in time (for the same VCS root it is the same revision number). For a queued build chain (all builds linked with a snapshot dependency), the revision to use is determined after adding builds to the queue. At this time, all the VCS roots of the chain are checked for changes and the current revision is fixed in the builds;

• if there is a snapshot dependency and artifact dependency on the Build from the same chain pointing to the same build configuration, TeamCity ensures the download of artifacts from the same-sources build.

• by default, builds that are a part of a build chain are preserved from clean-up, but this can be switched on a per-build configuration basis. Refer to the Clean-Up description for more details.

Depending on the dependencies, topology builds can run sequentially or in parallel.

Behavior on the build chain continuation in case of a build failure is customizable via the snapshot dependency options. For each failed or failed to start dependency you can select one of the four 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 a problem was not muted earlier)

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

• Mark build as 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".

A build of a chain can reference parameters from the preceding builds via dep.<configurationId>.<parameterName> syntax.

There is a special support for pushing parameters down the chain when a build with snapshot dependencies is triggered. It is done by defining a parameter with reverse.dep.<configurationId>.<parameterName> name.

When setting up triggers for the builds in the chain, the recommended approach is: think about the result — the build you want to get at the end of the process, and configure triggers in its corresponding, "top" build configuration. No triggers are necessary in the build configurations this top one depends on, as their builds will be put into the queue automatically when the top one is triggered.
See also the related "Trigger on changes in snapshot dependencies" setting of a VCS trigger and the "Show changes from snapshot dependencies" checkbox in the "Version Control Settings" configuration section.

Let's consider an example to illustrate how snapshot dependencies work.

Let's assume that we have two build configurations, A and B, and configuration A has a snapshot dependency on configuration B and revisions synchronization is enforced.

1. When a build of configuration A is triggered, it automatically triggers a build of configuration B, and both builds will be placed into the build queue. Build B starts first and build A will wait in the queue till build B is finished (if no other specific options are set).

2. When builds B and A are added to the queue, TeamCity adjusts the sources to include in these builds. All builds will be run with the sources taken at the moment the builds were added to the queue.

3. When the build B has finished and if it finished successfully, TeamCity will start to run build A.

The example above shows the core basics of snapshot dependencies as a straightforward process without any additional options. For snapshot dependency options, refer to the Snapshot Dependencies page.

Artifact Dependency

Artifact dependencies provide you with a convenient means to use the output (artifacts) of one build in another build. When an artifact dependency is configured, the necessary artifacts are downloaded to the agent before the build starts. You can then review what artifacts were used in the build or what build used the artifacts of the current build using the Dependencies tab of build results.

To create and configure an artifact dependency, use the Dependencies build configuration settings page. If you need to download the artifacts inside a build script or locally, you can use the REST API or Ivy Ant tasks for that.

Notes on Cleaning Up Artifacts

Artifacts may not be cleaned if they were downloaded by other builds and these builds are not yet cleaned up. For a build configuration with configured artifact dependencies, you can specify whether the artifacts downloaded by this configuration from other builds can be cleaned or not. This setting is available on the clean-up policies page.