TeamCity Build Chain Dependencies: Architecture Note

Problem and Takeaway

When a source change occurs, downstream builds must start automatically with the exact same source revision (snapshot) or with the correct built artifact (artifact). Manually bumping version numbers is error‑prone and breaks reproducibility. The useful takeaway is that TeamCity satisfies this requirement with a lightweight internal directed‑acyclic‑graph (DAG) stored in its server database, without needing an external orchestrator.

Requirements

1. A change in a VCS root must queue all builds that depend on that revision.
2. Artifacts produced by a build must be reliably propagated to dependent builds.
3. Users should be able to declare either snapshot dependencies (same revision) or artifact dependencies (specific version) without manual version updates.

Minimal Design

TeamCity persists each build configuration as a node in an internal DAG. Every edge records:

• dependency type: snapshot or artifact
• source build configuration identifier
• a version constraint evaluated at queue time (for snapshot: "same revision"; for artifact: "exact build number" or "latest successful")

During queue processing the server walks the graph, resolves constraints, and places dependent builds in the queue with a "Waiting for dependency" status. No separate workflow engine is required.

Trust and Data Boundaries

The server trusts build agents to:

• report their assigned build number and status
• make produced artifacts available in the agent’s work directory under system/artifacts/

Agents isolate artifact storage per build; they cannot read another build’s artifact directory. The server enforces dependency resolution, preventing an agent from pulling artifacts it did not produce. This separation keeps the trust boundary at the agent‑to‑server communication channel.

Operational Checks

Administrators can:

• Enable dependency‑resolution debug logging via Administration → Diagnostics → Debug logging and add the logger teamcity.debug.dependency at DEBUG level.
• Watch the build queue for builds stuck in "Waiting for dependency" and note the displayed dependency name.
• Use the built‑in Dependency Viewer (Administration → Projects → → Dependencies) to inspect the graph, spot missing edges, or detect cycles.
• Query the internal database table dependencies (accessible through a TeamCity backup or direct SQL with read‑only credentials) to confirm each edge stores dependency_type, source_build_type_id, and version_constraint.

Practical Verification Steps

1. Enable the debug logger as described above; note that this may increase log volume on busy servers.
2. Create two build configurations: Compile (runs a Maven build) and Package (depends on the artifact from Compile).
3. In Package’s settings, add an artifact dependency on Compile with Artifacts to download: **/* and Get artifacts from: Builds on the same branch.
4. Commit a change to the VCS root watched by Compile and observe the server log for a DEBUG line similar to:

[DEBUG] teamcity.debug.dependency - Resolved artifact dependency: Package <- Compile (build #123)

5. Check the build queue: Compile should start first; Package appears with status "Waiting for dependency: Compile".
6. After Compile finishes successfully, verify that Package starts and that its work directory contains the expected artifacts under system/artifacts/.

Failure Modes and Design Change Triggers

• Agent loss or artifact cleanup: If an agent’s work directory is purged (e.g., by a disk‑space policy) after a build finishes, downstream artifact‑dependency builds will fail with a missing‑artifact message. The server does not automatically rebuild the producer; manual re‑run or a retention policy that preserves needed artifacts is required.
• Misconfigured snapshot dependencies: A circular snapshot dependency (A depends on B, B depends on A) is not blocked at configuration time. When either build enters the queue, the server detects the cycle and leaves both builds in "Waiting for dependency" indefinitely, requiring manual intervention to break the loop.
• Clock drift: Snapshot dependencies compare revisions based on server‑side timestamps; significant drift between server and agents can cause false equality/inequality checks, leading to unnecessary rebuilds or missed triggers.
• Shift to immutable cloud artifact stores or Kubernetes‑based agents: The current model assumes mutable agent‑local artifact storage. Moving to an immutable store (e.g., S3 with versioned objects) or to short‑lived K8s agents would require the server to treat artifacts as externally addressable resources, changing the trust boundary and possibly introducing a separate artifact‑resolution service.

Limitations and How to Check Results

The dependency model does not prevent configuration‑time cycles; they surface only at runtime. To mitigate:

• Periodically run the Dependency Viewer and look for red‑highlighted cycles.
• Enable the debug logger and watch for "Circular dependency detected" messages.

Artifact‑dependency reliability hinges on agent‑side artifact retention. Verify retention policies under Administration → Server Configuration → Artifact Storage Clean‑up Rules and ensure that the artifact-dependency rule is set to "Do not clean" for builds that are consumers.

To confirm that a dependent build correctly waited for its predecessor, after a run inspect the build’s Changes tab: it should list the same VCS revision as the producer when a snapshot dependency is used, or show the exact build number of the producer when an artifact dependency is used.

Conclusion

TeamCity’s built‑in dependency mechanism fulfills the core requirements for reliable build chains with a minimal server‑side DAG, clear trust boundaries, and straightforward operational visibility. By using the Dependency Viewer, debug logging, and routine checks of the internal dependencies table, administrators can confirm correct behavior, detect failure conditions early, and understand when architectural changes (e.g., moving to immutable artifact stores) would necessitate a redesign.