Dependencies & Build Chains

A snapshot dependency enforces that two build configurations use the exact same source code revision. When Build B has a snapshot dependency on Build A, TeamCity guarantees:

• Build A runs first; Build B only starts after A completes
• Both builds check out the same commit SHA
• If Build A fails, Build B is not triggered

Adding a snapshot dependency

1. Open the downstream build configuration (e.g., Deploy).
2. Go to Dependencies → Add new snapshot dependency.
3. Select the upstream build config (e.g., Build).
4. Configure options (see table below).
5. Save.

"Suitable build" matching

TeamCity searches for an existing build of the upstream config that used the same VCS revision. If found and successful, it reuses it (skips re-running). This is the key to efficient build chains — a commit that already passed the Build stage won't rebuild it just because Deploy was triggered again.

Clean checkout on dependency

If "Clean sources" is enabled on the downstream config, its checkout is wiped even though the snapshot ensures the same revision. This is correct behaviour — the clean checkout is about the working directory state, not the revision.

An artifact dependency copies files published by one build configuration into the working directory of another, before the build starts. It does not enforce build ordering — it just copies files. Combine with a snapshot dependency for ordered artifact passing.

Adding an artifact dependency

1. Open the consuming build config (Deploy).
2. Go to Dependencies → Add new artifact dependency.
3. Select the producing build config (Build).
4. Set artifact path pattern and target path.

# Artifact path examples (relative to producing build's artifact root):

# Copy a specific JAR into current dir
artifacts/myapp-*.jar

# Copy all files from a published directory
release/** => downloaded-release

# Copy specific files to a named directory
target/myapp.jar => libs
target/config.properties => config

# Pattern syntax:
# source-pattern           => target-dir (optional)
# source-pattern supports: *, **, ?
# target-dir: where to place files in downstream working dir

Artifact dependency build selection

TeamCity automatically generates a visual build chain diagram. To view it: click any build in the chain → Dependencies tab → Build chain view.

The chain view shows the status (green/red/running) of each build in the chain, the build number, start time, and duration. Failed builds are immediately visible — you can click to jump to the log.

A composite build configuration aggregates results from multiple builds into a single "pass/fail" result. It has no build steps of its own — it simply waits for all its snapshot dependencies to complete and reports a combined status.

Use cases:

• Parallel test shards: Run 5 test configurations in parallel; the composite passes only when all 5 pass.
• Multi-platform builds: Build on Linux, Windows, macOS simultaneously; composite aggregates results.
• Branch gate: Set a GitHub branch protection rule requiring the composite build to pass — one check covers the whole pipeline.

Creating a composite build

1. Create a new build configuration.
2. In General Settings → Build configuration type, select Composite.
3. Add snapshot dependencies on the builds you want to aggregate.
4. No build steps needed — the composite has no agent requirements and no build steps.
5. The Commit Status Publisher on the composite will report the aggregated status to GitHub.

When enabled on a snapshot dependency, TeamCity ensures the downstream build runs on the same agent as the upstream build. This is needed when:

• Builds share a local filesystem cache (e.g., Docker layer cache between build and test)
• Builds use a hardware device or license locked to one machine
• The build produces files to a local path that the next step needs (avoid this with artifact publishing instead)

Clean checkout on a downstream config wipes its working directory. This is independent of the snapshot dependency — the same revision is checked out fresh. Be aware that artifact dependencies run AFTER clean checkout — the downloaded artifacts won't be deleted by clean checkout.

# Execution order within a downstream build:
# 1. Clean checkout (if enabled) — wipes working dir
# 2. VCS checkout — checks out the snapshot-matched revision
# 3. Artifact dependencies downloaded — files placed in working dir
# 4. Build steps run

# So artifact dependencies survive clean checkout — ✅ correct behaviour

Downstream builds can read any parameter from an upstream build using the dep. prefix (see Phase 8). This includes predefined parameters like the build number:

# In Deploy build config (which has snapshot dep on Build):
# Read Build's build number:
dep.ProjectId_BuildConfigId.build.number

# Example with a real config ID:
# Project: BackendServices, Config: Build → ID: BackendServices_Build
dep.BackendServices_Build.build.number

# In a deploy step:
echo "Deploying artifact version: %dep.BackendServices_Build.build.number%"
kubectl set image deployment/myapp myapp=registry/myapp:%dep.BackendServices_Build.build.number%

Key design decisions

• Compile is separate: Unit Tests and Integration Tests both depend on Compile, so they can run in parallel — neither waits for the other.
• Package depends on Compile only: This enables parallel test runs. Package uses a "suitable build" — if Compile already passed, it doesn't rerun.
• Deploy Prod requires Deploy Staging to pass: Prevents direct prod deploys. Snapshot dep on Staging = same revision all the way through.
• Prod has prompt parameter: A developer must manually confirm before prod deploy runs.