TeamCity build chains with snapshot and artifact dependencies

Problem and takeaway

A CI pipeline that checks out the same repository in every build configuration wastes agent time and risks testing different source revisions across stages. Publishing every intermediate binary to an external repository just to move it from compile to package adds storage cost and operational overhead.

Use TeamCity snapshot dependencies to share the same checked-out sources across build configurations, and artifact dependencies to pass only the binaries a downstream stage needs. The TeamCity server resolves the chain and stores artifacts; agents execute the builds. Keep the design small, verify artifact retention after upgrades, and do not treat chain status as a security boundary.

Requirements

• One VCS root per project.
• One build configuration per stage, for example compile, test, and package.
• Source consistency across stages without duplicate checkouts.
• Downstream builds consume binaries only after the upstream build finishes successfully.
• Access controlled by TeamCity project roles.

Smallest suitable design

Create three build configurations in one TeamCity project:

Configuration	Dependencies	Purpose
Compile	None	Checks out sources and builds.
Test	Snapshot dependency on Compile	Runs tests against the same source revision.
Package	Snapshot dependency on Test; artifact dependency on Test	Publishes and consumes build outputs such as JARs or ZIPs.

Configuring the chain in the TeamCity web UI

1. Open Project Settings > Build Configurations. Required permission: project administrator or build configuration editor.
2. Create Compile with a VCS root pointing to the repository.
3. Create Test. On the Dependencies tab, add a snapshot dependency on Compile. Optionally enable "Run build on the same agent" if the test needs files left in the agent workspace.
4. Create Package. Add a snapshot dependency on Test, then add an artifact dependency on Test with an artifact rule such as myapp/target/*.jar => .
5. Set Test to trigger automatically when Compile finishes, and Package to trigger automatically when Test finishes. Add manual or scheduled triggers only if you need release promotion gates.

Expected check: the Build Chain graph shows Compile → Test → Package. When you commit a change, Compile starts, then Test starts after Compile finishes successfully, then Package starts and downloads the JAR. Risk: if Compile fails, Test and Package do not start.

Trust and data boundaries

The TeamCity server is the trust boundary for chain state. Dependency resolution happens server-side: the server determines which upstream build satisfies a snapshot or artifact dependency and orders execution. Agents run individual builds and report status back; they do not negotiate the chain directly.

Artifacts are published to the server and consumed by downstream builds through artifact dependencies. Access is controlled by project roles and agent authorization. Build chain status is not a security boundary: permissions are enforced at the project and role level, not by the chain graph itself.

Operational checks

• Open the Dependencies tab and the build chain graph to confirm direction and triggering rules.
• Run the chain and confirm the downstream build starts after the upstream build finishes and receives the published artifact.
• Inspect agent logs for artifact upload or download errors.
• Review project roles and artifact cleanup rules under project settings to confirm who can trigger builds and how long artifacts are retained.
• Re-check behavior after a TeamCity upgrade or agent OS patch, because dependency resolution and artifact storage paths can change between versions.

Failure modes

• Dependency build failure blocks all downstream builds in the chain.
• Agent loss during artifact upload can leave partial artifacts on the server.
• Cleanup rules can remove artifacts before a downstream build consumes them.
• A failed build may publish partial artifacts if cleanup rules are misconfigured. Validate checksums or restrict consumption to finished builds only.
• Firewalls or NAT between agents and the server can interrupt artifact transfer and mark builds as failed.

Conditions that would change the design

• Cross-team artifact sharing: use an external artifact repository such as Nexus, Artifactory, or an S3-compatible store instead of TeamCity artifacts.
• Multi-branch pipelines: use branch specifications or separate chains per branch rather than a single linear chain.
• Long-term immutable storage: move release candidates to an external repository; TeamCity artifacts are intended for pipeline consumption, not archival.

Limitations and practical verification

TeamCity artifacts are not a general artifact repository. Retention is configurable and cleanup behavior varies by installed version, so verify against your TeamCity version before relying on automatic cleanup. A snapshot dependency shares sources but does not guarantee binary reproducibility; a clean rebuild can still produce different outputs.

Practical verification: make a VCS change, watch Compile run, then confirm Test uses the same revision on its Changes tab and Package finds the expected artifact on its Artifacts tab. If an artifact is missing, check the upstream build's Finished status, the artifact rules, and the agent logs.

Rollback

Adding or removing a dependency changes TeamCity configuration state. To roll back, open the downstream build configuration, go to the Dependencies tab, delete the dependency, and save. Existing builds and artifacts are not deleted, but downstream builds will no longer trigger automatically.