In TeamCity, what is the Kotlin DSL, and how does a .teamcity/settings.kts file in your repository become the server's build configuration?

## The problem the DSL solves TeamCity is a server-side CI product: historically you created a project, added build configurations, and clicked your way through VCS roots, triggers, build steps and dependencies. That configuration lived in the server's Data Directory as XML, not in your repository. It worked, but it meant configuration was not reviewable in pull requests, not versioned with the code it built, and painful to duplicate across dozens of near-identical services. The **Versioned Settings** feature moves a project's settings into a VCS root. You choose a format — XML (essentially the server's own storage format) or **Kotlin**, the typed DSL. Kotlin format is what people mean when they say "TeamCity Kotlin DSL". ## What lives in the repository With Kotlin format enabled, TeamCity generates a `.teamcity` directory in the repository. Its entry point is `settings.kts`. Alongside it sits a Maven project descriptor so an IDE can resolve the DSL library from the server and give you completion and navigation over the real API — the same jars the server compiles against. A minimal script looks like this: ```kotlin import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.gradle import jetbrains.buildServer.configs.kotlin.triggers.vcs version = "2025.03" project { buildType(Build) } object Build : BuildType({ name = "Build" vcs { root(DslContext.settingsRoot) } steps { gradle { tasks = "clean build" } } triggers { vcs { } } }) ``` Three things are worth noticing. The `version` value pins the DSL API version, which is tied to the TeamCity server version — an old server cannot compile a script written against a newer API. `DslContext.settingsRoot` refers to the VCS root the settings themselves came from, so the script does not have to hardcode a repository URL. And `object Build : BuildType({ ... })` is ordinary Kotlin: the configuration is a value in a program, not a document. ## How the server applies it On each change to the settings VCS root, the server checks the settings out, compiles the Kotlin, executes it to produce an in-memory model of projects and build configurations, and reconciles that model with what the project currently has. Because it is a compile-then-run step, an error in your script is a **compilation failure surfaced on the project's Versioned Settings page**, and the server continues serving the last settings it successfully applied. That is a meaningful safety property: a bad commit to `settings.kts` breaks the settings update, not the ability to run builds. Synchronization has a direction. In one-way mode, VCS is authoritative and UI edits are either forbidden or transient. In two-way mode, edits made in the UI are committed back to the repository by the server, which is convenient for people who prefer clicking but produces machine-authored commits that reviewers must read. ## Identity and history Each build configuration carries a stable ID derived from its object name and the project, plus a UUID recorded in the DSL for entities created through the UI. The IDs are how builds, history and artifacts stay attached to a configuration. Renaming an object so its ID changes — or changing a UUID — makes TeamCity treat it as a different configuration and detach the old build history. This is the most common self-inflicted injury when refactoring a DSL, and the reason people rename cautiously and check the generated IDs. ## Secrets Settings in VCS must not carry plaintext credentials. TeamCity handles this by keeping secure values on the server and writing a token into the DSL instead: a password parameter appears as a `credentialsJSON:` value referencing the server-stored secret. The consequence is that a `settings.kts` file is not fully portable to another server on its own — the referenced secrets have to exist there too. ## When it is worth it The DSL pays off when you have many similar configurations: a function or loop that emits one build configuration per service replaces dozens of hand-maintained copies, and a change to the shared function updates all of them at once. Templates and inheritance from the classic model still exist and are expressible in the DSL. For a project with two build configurations that rarely change, the extra machinery — a compile step, an API version coupled to the server, Kotlin knowledge in review — mostly buys ceremony.