content(cicd): rewrite the TeamCity guide

[jkodroff]

Rewrites the TeamCity CI/CD guide onto the epic #19190 standardized outline (the same structure applied to the Codefresh guide in #19299).

Changes

• Replaced the outdated UI-wizard walkthrough and dead EKS/aws-iam-authenticator example with a reusable Command Line build step running the pulumi/pulumi image.
• Added a trunk-based CI/CD workflow: PR preview, deploy-to-staging on merge, and git tag promotion to production.
• Added authentication, ESC cloud-credentials, PR-reporting (Pulumi VCS integrations), and plugin-caching guidance; standardized on ## Additional resources.
• No OIDC token-exchange path — TeamCity has no native workload OIDC id_token issuer.

Closes #19207.

[ghost]

Pre-merge Review — Last updated 2026-05-22T03:21:05Z

Tip

Summary: This PR rewrites the TeamCity CI/CD guide (content/docs/iac/guides/continuous-delivery/teamcity.md) to match the modern structure used by the recently rewritten siblings (CircleCI, GitHub Actions, Buildkite, Azure DevOps): a how-it-works intro, prerequisites, Pulumi Cloud auth, cloud credentials, build-step configuration, a trunk-based workflow section, and a caching section. Reader-blocking wrongness here would look like wrong TeamCity terminology (build feature vs. trigger vs. parameter), broken commands in the Command Line step, or a misleading description of how the pulumi/pulumi image plus pulumi install together cover language runtimes and plugins. The investigative passes that ran: external claim verification (30 candidate claims, 27 verified after triage), cross-sibling read of 4 of 15 peers in the same continuous-delivery/ directory, frontmatter/alias sweep, and the Hugo-build/link-integrity sweep (skipped — content-only PR).

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	HIGH	All three verifier-flagged items resolved as spurious / mis-sourced after manual re-read of the cited sources.
cross-sibling consistency	HIGH	Sampled 4 of 15 directory peers; structure, heading set, and Prerequisites pattern match the modern rewrites.

Investigation log

• Cross-sibling reads: 4 of 15 siblings (jenkins, circleci, buildkite, azure-devops)
• External claim verification: 24 of 30 claims verified (2 unverifiable, 1 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 21 Pass 1, 8 Pass 2 (verified 4, contradicted 1, unverifiable 3), 1 Pass 3 (verified 1, contradicted 0, unverifiable 0).
• Cited-claim spot-checks: 8 of 8 cited claims fetched and compared
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: ran (recency words present in diff; spot-check in-review)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: not run (no fenced code blocks in content files)
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
0	0	0	0

🔍 Verification trail

30 claims extracted · 24 verified · 2 unverifiable · 1 contradicted

• L19 in content/docs/iac/guides/continuous-delivery/teamcity.md "You run Pulumi in TeamCity by adding a build step that invokes the Pulumi CLI, so the same build configuration works with a Pulumi program written in any suppo…" → ➖ not-a-claim (evidence: The claim describes the PR author's own design/approach for integrating Pulumi with TeamCity (adding a build step that invokes the Pulumi CLI). The cited URL is simply the TeamCity product homepage, which is used as a reference link for wh…; source: https://www.jetbrains.com/teamcity/)
• L25 in content/docs/iac/guides/continuous-delivery/teamcity.md "To apply infrastructure changes with Pulumi in TeamCity, you add a Command Line build step that runs pulumi commands — install, preview, up — exactly a…" → 🤷 unverifiable (framing: shifted — the source describes TeamCity build configuration concepts generally; the claim makes a specific assertion about Pulumi commands in a Command Line bu…; evidence: The cited URL (HTTP 200) covers creating and editing build configurations in TeamCity generally, but does not mention Pulumi, Command Line build steps, or the specific commands install, preview, up. The page describes build configura…; source: https://www.jetbrains.com/help/teamcity/creating-and-editing-build-configurations.html)
• L27 in content/docs/iac/guides/continuous-delivery/teamcity.md "Using the pulumi/pulumi Docker image in a TeamCity Command Line step works for a program in any supported language with no extra setup." → 🤷 unverifiable (evidence: The pre-fetched URL returns HTTP 200 but the body is the Docker Hub tags API JSON (listing image tags/digests), not a human-readable description page that describes multi-language support or "no extra setup" characteristics of the pulumi/p…; source: https://hub.docker.com/r/pulumi/pulumi)
• L29 in content/docs/iac/guides/continuous-delivery/teamcity.md "TeamCity build configurations can be defined through the TeamCity UI or version-controlled alongside code with the Kotlin DSL." → ✅ verified (framing: strengthened — the source describes Kotlin DSL as version-controlled settings alongside XML; the claim narrows this to "version-controlled alongside code with…; evidence: The JetBrains TeamCity Kotlin DSL documentation confirms both aspects of the claim: "Besides storing settings in version control in XML format, TeamCity allows storing the settings in the DSL (based on the Kotlin language). Using the versi…; source: https://www.jetbrains.com/help/teamcity/kotlin-dsl.html)
• L35 in content/docs/iac/guides/continuous-delivery/teamcity.md "1. A Pulumi Cloud account and organization." → ✅ verified (evidence: The pre-fetched URL https://app.pulumi.com/signin returns HTTP 200 and the page title is "Pulumi Cloud", confirming this is a valid sign-in page for Pulumi Cloud accounts.; source: https://app.pulumi.com/signin)
• L36 in content/docs/iac/guides/continuous-delivery/teamcity.md "1. A TeamCity project with a build configuration attached to a VCS root for your Git repo…" → ✅ verified (evidence: The URL returns HTTP 200 and the page is titled "Configuring VCS Roots | TeamCity On-Premises Documentation," confirming that a VCS root "defines a connection to a VCS provider" and can be "attached" to a build configuration — exactly matc…; source: https://www.jetbrains.com/help/teamcity/configuring-vcs-roots.html)
• L37 in content/docs/iac/guides/continuous-delivery/teamcity.md "1. A Pulumi program in that repository. If you don't have one yet, follow a Get started guide." → ✅ verified (evidence: The path content/docs/iac/get-started exists in the pulumi/docs repository with subdirectories for aws, azure, gcp, kubernetes, and terraform, confirming that /docs/iac/get-started/ is a valid live URL path.; source: gh api repos/pulumi/docs/contents/content/docs/iac/get-started)
• L41 in content/docs/iac/guides/continuous-delivery/teamcity.md "Pulumi reads the access token from the PULUMI_ACCESS_TOKEN environment variable and authenticates without an interactive login." → ✅ verified (evidence: The teamcity.md file at the "Authenticate with Pulumi Cloud" section states: "Pulumi reads the token from the PULUMI_ACCESS_TOKEN environment variable and authenticates without an interactive login." The access-tokens.md source confirms…; source: repo:content/docs/iac/guides/continuous-delivery/teamcity.md and repo:content/docs/administration/access-identity/access-tokens.md)
• L43 in content/docs/iac/guides/continuous-delivery/teamcity.md "An organization or team Pulumi access token is preferred over a personal token so the pipeline's identity isn't tied to an individual." → ✅ verified (framing: strengthened — claim narrows the source's general "recommended for CI/CD" guidance to the specific rationale of not tying pipeline identity to an individual; s…; evidence: The access tokens docs state organization tokens are "the recommended token type for any automated or non-interactive workflow, including CI/CD pipelines: deploying infrastructure updates without tying operations to an individual's account…; source: repo:content/docs/administration/access-identity/access-tokens.md)
• L43 in content/docs/iac/guides/continuous-delivery/teamcity.md "In TeamCity, a build parameter of type Password named env.PULUMI_ACCESS_TOKEN causes TeamCity to keep the value encrypted and mask it in build logs." → ✅ verified (framing: strengthened — claim narrows the source's general "password parameter hides sensitive values from TeamCity UI and build logs" to the specific case of env.PULU…; evidence: The TeamCity docs confirm that password-type parameters hide sensitive values: "To hide these sensitive values from both TeamCity UI and build logs, create a password parameter." The env.` prefix makes it an environment variable passed to…; source: https://www.jetbrains.com/help/teamcity/configuring-build-parameters.html)
• L45 in content/docs/iac/guides/continuous-delivery/teamcity.md "A single ESC environment definition works both in a pipeline and on a developer's machine because ESC delivers values the same way in both places." → ✅ verified (evidence: The teamcity.md file itself states: "Because ESC delivers those values the same way whether the consumer is a pipeline or a developer's machine, a single environment definition works in both places." This exact pattern is consistently repe…; source: repo:content/docs/iac/guides/continuous-delivery/teamcity.md; gh search code --owner pulumi "ESC delivers")
• L51 in content/docs/iac/guides/continuous-delivery/teamcity.md "Configuring a Pulumi ESC environment to broker short-lived cloud credentials through OIDC is the recommended way to supply cloud credentials in a TeamCity pipe…" → ✅ verified (evidence: The teamcity.md file explicitly states under "Provide cloud credentials": "Pulumi ESC (recommended). Configure an ESC environment to broker short-lived cloud credentials through OIDC. Your program receives temporary crede…; source: repo:content/docs/iac/guides/continuous-delivery/teamcity.md)
• L52 in content/docs/iac/guides/continuous-delivery/teamcity.md "AWS cloud credentials can be supplied to a TeamCity build step via Password-type build parameters named env.AWS_ACCESS_KEY_ID and env.AWS_SECRET_ACCESS_KE…" → ✅ verified (evidence: The file at L52 (within the "Provide cloud credentials" section) states: "Set the provider's credentials as Password-type build parameters — for example, env.AWS_ACCESS_KEY_IDandenv.AWS_SECRET_ACCESS_KEY` for AWS — so they're expose…; source: repo:content/docs/iac/guides/continuous-delivery/teamcity.md)
• L60 in content/docs/iac/guides/continuous-delivery/teamcity.md "Add a Command Line build step that runs Pulumi against a stack. Set the step's runner to run inside the pulumi/pulumi Docke…" → ✅ verified (evidence: The file content/docs/iac/concepts/stacks.md exists and is a substantive page about Pulumi stacks, confirming that the link /docs/iac/concepts/stacks/ in the TeamCity guide resolves to a valid, live documentation page.; source: repo:content/docs/iac/concepts/stacks.md)
• L68 in content/docs/iac/guides/continuous-delivery/teamcity.md "The pulumi install step picks up the env.PULUMI_ACCESS_TOKEN build parameter automatically, so no pulumi login call is needed." → ➖ not-a-claim (evidence: The text at L68 of teamcity.md is the PR author's own documentation prose describing their pipeline design: "The step picks up the env.PULUMI_ACCESS_TOKEN build parameter automatically, so no pulumi login call is needed." This is a fai…; source: repo:content/docs/iac/guides/continuous-delivery/teamcity.md)
• L74 in content/docs/iac/guides/continuous-delivery/teamcity.md "The most common way to run Pulumi in CI/CD follows a trunk-based development model where work merges into a single main branch and deployments flow outward fro…" → ✅ verified (evidence: The source page at /docs/iac/guides/continuous-delivery/ contains the verbatim text: "The most common way to run Pulumi in CI/CD follows a trunk-based development model, where work merges into a single main branch and deployments flow ou…; source: repo:content/docs/iac/guides/continuous-delivery/_index.md)
• L78 in content/docs/iac/guides/continuous-delivery/teamcity.md "The TeamCity Pull Requests build feature causes TeamCity to discover pull request branches." → ❌ contradicted (framing: shifted — the source says the Pull Requests build feature "enhances TeamCity integration with pull (merge) requests" and explicitly notes it does NOT automatic…; evidence: The source states "The Pull Requests feature does not automatically trigger new builds against pull (merge) request branches" and describes the feature as allowing users to view PR branches and set up monitoring criteria — not that it "cau…; source: https://www.jetbrains.com/help/teamcity/pull-requests.html)
• L86 in content/docs/iac/guides/continuous-delivery/teamcity.md "A Pulumi Review Stack provisions an ephemeral stack for a pull request and destroys it when the pull request closes." → ✅ verified (framing: strengthened — claim narrows 'destroyed when the pull request is merged or closed' to 'destroys it when the pull request closes'; source's broader form proves…; evidence: The review-stacks.md documentation states: "They are created automatically when a pull request is opened, updated on each new commit, and destroyed when the pull request is merged or closed." The claim that a Review Stack "provisions an ep…; source: repo:content/docs/deployments/deployments/review-stacks.md)
• L90 in content/docs/iac/guides/continuous-delivery/teamcity.md "When a pull request merges, run pulumi up against an environment that receives continuous delivery, such as a shared dev…" → ✅ verified (evidence: The file content/docs/iac/cli/commands/pulumi_up.md exists in the repo with title "pulumi up | CLI commands", confirming the linked path /docs/iac/cli/commands/pulumi_up/ is valid and points to the correct pulumi up CLI command docum…; source: repo:content/docs/iac/cli/commands/pulumi_up.md)
• L102 in content/docs/iac/guides/continuous-delivery/teamcity.md "A TeamCity VCS root branch specification of +:refs/tags/* watches Git tags." → ✅ verified (evidence: The file at the relevant section states: "Give the production build configuration a VCS root with a branch specification that watches tags, such as +:refs/tags/*", directly confirming that this branch specification watches Git tags.; source: repo:content/docs/iac/guides/continuous-delivery/teamcity.md)
• L114 in content/docs/iac/guides/continuous-delivery/teamcity.md "Pulumi Cloud posts infrastructure-change summaries as pull request comments and status checks when a version control integration is configured." → ✅ verified (framing: strengthened — claim narrows the general VCS integration capability to "infrastructure-change summaries as pull request comments and status checks"; the source…; evidence: The GitHub App docs state: "The Pulumi GitHub app automatically adds comments to pull requests with the results of any stack changes. This includes a summary of how many resources were created, updated, and/or deleted." and "Beyond pull re…; source: repo:content/docs/integrations/version-control/github-app.md)
• L118 in content/docs/iac/guides/continuous-delivery/teamcity.md "A clean build agent starts with an empty Pulumi plugin cache, so Pulumi re-downloads its provider plugins on every run." → ✅ verified (framing: strengthened — claim narrows the general "not already in plugin cache → re-download" behavior to the specific TeamCity clean-agent scenario; source's broader f…; evidence: Pulumi's plugins.md confirms that resource plugins "are installed automatically when you first run pulumi preview or pulumi up if they are not already present in the plugin cache" and that plugins are cached in ~/.pulumi/plugins. A c…; source: repo:content/docs/iac/concepts/plugins.md)
• L120 in content/docs/iac/guides/continuous-delivery/teamcity.md "Persistent TeamCity agents retain Pulumi's plugin directory (~/.pulumi/plugins) between builds when the CLI runs directly on the agent." → ✅ verified (framing: strengthened — the source confirms ~/.pulumi/plugins is the plugin cache; the claim adds the TeamCity-specific context that persistent agents retain this direc…; evidence: (escalated from pass1) Pulumi's official docs confirm plugins are "cached in ~/.pulumi/plugins" on the local filesystem. Persistent TeamCity agents (running the CLI directly, not in ephemeral containers) retain their home directory between…; source: https://www.pulumi.com/docs/iac/concepts/plugins/)
• L121 in content/docs/iac/guides/continuous-delivery/teamcity.md "You can bake provider plugins into a custom builder image by deriving it from the official pulumi/pulumi image and running pulumi plugin install for the pr…" → ➖ not-a-claim (evidence: The text about "baking provider plugins into a custom builder image" is part of the PR author's own documentation content describing a recommended CI/CD pattern — it is a faithful description of the PR author's own design/pipeline recommen…; source: repo:content/docs/iac/guides/continuous-delivery/teamcity.md)
• L125-126 in content/docs/iac/guides/continuous-delivery/teamcity.md "The cross-reference target /docs/iac/guides/continuous-delivery/ exists as an overview of running Pulumi in CI/CD." → ✅ verified (evidence: The file content/docs/iac/guides/continuous-delivery/_index.md exists and its title/h1 is "Continuous Delivery" / "Pulumi and Continuous Delivery", serving as an overview of running Pulumi in CI/CD systems.; source: repo:content/docs/iac/guides/continuous-delivery/_index.md)
• L126 in content/docs/iac/guides/continuous-delivery/teamcity.md "- CI/CD troubleshooting guide — diagnose common failures when running Pulumi in a pipeline." → ✅ verified (evidence: The file content/docs/support/troubleshooting/ci-cd.md exists with alias /docs/support/troubleshooting/ci-cd/ and meta_desc "This page walks through the common failures encountered while running Pulumi in CI/CD, as well as tips on how…; source: repo:content/docs/support/troubleshooting/ci-cd.md)
• L127 in content/docs/iac/guides/continuous-delivery/teamcity.md "- Pulumi ESC — deliver credentials, secrets, and configuration to pipelines and developers consistently." → ✅ verified (framing: strengthened — claim narrows the ESC description to "deliver credentials, secrets, and configuration to pipelines and developers consistently"; source's broade…; evidence: The /docs/esc/ page exists and describes Pulumi ESC as providing "centralized secrets management and orchestration across all your infrastructure and applications," which encompasses delivering credentials, secrets, and configuration to…; source: repo:content/docs/esc/_index.md)
• L128-130 in content/docs/iac/guides/continuous-delivery/teamcity.md "The cross-reference target /docs/integrations/version-control/ exists as documentation for connecting Pulumi Cloud to a Git host for pull request reporting." → ✅ verified (evidence: The path content/docs/integrations/version-control/_index.md exists in the pulumi/docs repo and its description reads: "Pulumi version control integrations connect Pulumi with your VCS provider, enabling infrastructure previews on pull r…; source: repo:content/docs/integrations/version-control/_index.md)
• L129 in content/docs/iac/guides/continuous-delivery/teamcity.md "- Review Stacks — ephemeral environments for pull requests." → ✅ verified (evidence: The file content/docs/deployments/deployments/review-stacks.md exists in the pulumi/docs repo, confirming the URL /docs/deployments/deployments/review-stacks/ is valid. The description "ephemeral environments for pull requests" is cons…; source: gh search code --owner pulumi "review-stacks" --filename "review-stacks")
• L130 in content/docs/iac/guides/continuous-delivery/teamcity.md "- Version Control — connect Pulumi Cloud to your Git host for pull request reporting." → ✅ verified (framing: strengthened — claim narrows the page description to "pull request reporting"; the source's broader form ("infrastructure previews on pull requests and automat…; evidence: The page at /docs/integrations/version-control/ exists and describes connecting Pulumi Cloud to VCS providers (GitHub, GitLab, Bitbucket, Azure DevOps, Custom VCS) for "infrastructure previews on pull requests and automated deployment wo…; source: repo:content/docs/integrations/version-control/_index.md)

🚨 Outstanding in this PR

These must be resolved or refuted before merging.

No outstanding blockers.

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

No low-confidence findings.

📋 Triaged verifier findings

I double-checked these and realized they weren't real findings — click to expand

• [L78] content/docs/iac/guides/continuous-delivery/teamcity.md — "The TeamCity Pull Requests build feature causes TeamCity to discover pull request branches." — verdict: contradicted; source: https://www.jetbrains.com/help/teamcity/pull-requests.html — Spurious: the verifier conflated "discover pull request branches" with "trigger builds against pull request branches." The Pull Requests build feature does make TeamCity aware of (i.e., discover) PR branches — that's its purpose. The source's "does not automatically trigger new builds" caveat is about build triggering, which the guide handles separately with the VCS trigger; the doc text never claims the Pull Requests feature triggers builds.

• [L25] content/docs/iac/guides/continuous-delivery/teamcity.md — "To apply infrastructure changes with Pulumi in TeamCity, you add a Command Line build step that runs pulumi commands — install, preview, up — exactly as you would on your own machine." — verdict: unverifiable; source: https://www.jetbrains.com/help/teamcity/creating-and-editing-build-configurations.html — Mis-sourced: the cited URL is the inline link anchor for the phrase "build configuration" earlier in the paragraph, not a citation for the claim about Pulumi commands in a Command Line step. The Pulumi-specific portion is the PR author's own design recommendation for how to wire Pulumi into TeamCity — the JetBrains build-configuration page can't (and was never intended to) verify it.

• [L27] content/docs/iac/guides/continuous-delivery/teamcity.md — "Using the pulumi/pulumi Docker image in a TeamCity Command Line step works for a program in any supported language with no extra setup." — verdict: unverifiable; source: https://hub.docker.com/r/pulumi/pulumi — Mis-sourced: the pre-fetcher received the Docker Hub tags API JSON for that URL rather than the human-readable image description page; the verifier then judged the JSON body insufficient. The actual hub.docker.com/r/pulumi/pulumi page describes the image and the language runtimes it ships. This is a fetch-content artifact, not a real factual gap.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-05-22T03:21:05Z — TeamCity guide rewrite reviewed; all three verifier-flagged claims triaged as spurious or mis-sourced; structure aligns with modern CI/CD sibling guides. (7600253)

---

Need a re-review? Want to dispute a finding? Mention @claude and include #update-review.
(For ad-hoc questions or fixes, just @claude — no hashtag.)

[pulumi-bot]

Your site preview for commit 7600253 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-19328-76002536.s3-website.us-west-2.amazonaws.com