Dependent Build
In TeamCity one build configuration can depend on one or more configurations. Two types of dependencies can be specified:
An artifact dependency is just a way to get artifacts produced by one build into another. Without a corresponding Snapshot dependency, it is mainly used when the build configurations are not related in terms of sources. For example, one build provides a reusable component for others. A snapshot dependency influences the way builds are processed and implies that the builds are deeply related, one build being a logic part of another.
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 then 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: April, 2012, March, 2016
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.
The build results page of a build with snapshot dependencies allows reviewing all the dependency builds and their errors, if 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 of the 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 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 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".
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" check-box 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.
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).
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.
If the build configurations connected with a snapshot dependency share the same set of VCS roots, all builds will run on the same sources. Otherwise, if the VCS roots are different, changes in the VCS will correspond to the same moment in time.
When the build B has finished and if it finished successfully, TeamCity will start to run build A.
Please note that the changes to be included in build A could have become not the latest ones by the moment the build started to run. In this case, build A becomes a history build.
The above example shows the core basics of snapshot dependencies as a straight forward 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.
Please note that if both a snapshot dependency and an artifact dependency are configured for the same build configuration, in order for it to take artifacts from the build with the same sources, the Build from the same chain option must be selected in the artifact dependency.
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 cleanup policies page.