TeamCity 2017.2.2 Reference Cards

The agent registers itself but must be authorized manually in Administration → Agents → Unauthorized. Until authorized it will never pick up builds.

Artifact paths always use forward slashes / even on Windows agents. Backslashes silently produce no artifacts.

Every branch pattern must start with +: (include) or -: (exclude). A bare refs/heads/* with no prefix is invalid and monitors nothing.

+:refs/heads/* does NOT include the default branch unless the default branch is under refs/heads/. Add +:refs/heads/main explicitly or verify.

Cross-build parameters use dep.<ExternalID>.param. The external ID is case-sensitive and includes the project prefix. A single wrong character means the parameter stays blank with no error.

The bundled HSQL database is development-only. It does not support concurrent writes and corrupts under moderate load. Always migrate to MySQL or PostgreSQL before going live.

Only parameters whose type is explicitly set to Password are masked in logs. A system property or env var named env.SECRET will still print in full unless its type is Password.

If no agent satisfies a build's requirements the build sits in the queue forever with a "No compatible agents" note in small text. Always check agent compatibility before wondering why a build won't start.

Artifact dependency set to "latest successful build" will pick an artifact from a different chain run. Use "build from the same build chain" to guarantee you're testing the exact artifact you just built.

Without a quiet period, every single commit in a multi-commit push fires a separate build. Set a 60–120 second quiet period to batch commits from the same push into one build.

When you copy a build configuration the build counter continues from where the source left off. Reset it to 1 in General Settings if you want the new config to start from build #1.

Enabling "Clean all files before build" means full VCS checkout every time — safe but slow. Use it only for release builds; leave it off for developer feedback builds.

A composite build configuration is purely an aggregation node — it can have snapshot dependencies and parameters but no build steps. Adding steps to a composite config has no effect.

Detaching a build configuration from its template embeds the current state, but any parameters or steps that were identical to the template are not highlighted. Review all settings after detaching.

Enabling Versioned Settings with Kotlin DSL does not immediately export existing config. You must commit the generated XML first, then migrate to Kotlin — skipping the XML step causes a blank config import.

TeamCity defaults to XML responses. Add Accept: application/json to every API request or you'll parse XML instead of JSON. The Content-Type: application/json header is also required for POST bodies.

The default 750 MB heap is insufficient for large installations. On a server with 50+ projects and 500+ builds/day, increase -Xmx to at least 2–4 GB in TEAMCITY_SERVER_MEM_OPTS.

The SSH Agent build feature forwards the key to the agent JVM process but not to child processes spawned via shell scripts unless you explicitly eval the agent socket in the script.

In some 2017.x versions, cancelling a build while it holds a Shared Resource lock can leave the lock held until the next build finishes. Monitor the Shared Resources page if builds queue unexpectedly.

Notification rules apply to regular builds. Personal (pre-commit) builds only notify the build's owner unless you explicitly check "My personal builds" in the notification rule.