Skip to content

TeamCity CI/CD: builds, parameters and Kotlin DSL

TeamCity is JetBrains’ CI/CD server. A central server stores configuration, watches repositories and queues builds; build agents run the work and report results back. It is strong where builds are large and varied: .NET and Java monorepos, builds that need Windows, Linux and macOS agents side by side, and long chains of dependent builds that should reuse earlier results. This page covers the concepts in the order you configure them, using an invented OrdersPortal repository hosted on GitLab.

Facts on this page were checked against JetBrains’ TeamCity documentation source (JetBrains/teamcity-documentation, the 2026.3 branch) in November 2026. The Kotlin DSL samples follow that documentation but were not compiled or run here, because the TeamCity DSL libraries come from the TeamCity server or JetBrains’ repository, neither of which was reachable. TeamCity can generate and validate them locally with mvn teamcity-configs:generate in the .teamcity folder.

Topic What it answers
Server agents and projects The parts of a TeamCity installation and how work flows through them.
Build configurations Steps, triggers, artifacts and agent requirements.
VCS roots and branches Connecting repositories and choosing which branches build.
Parameters Configuration parameters, environment variables, system properties and secrets.
Templates Sharing settings across build configurations.
Kotlin DSL and versioned settings Keeping configuration in Git as code.
Build chains Snapshot and artifact dependencies between builds.
GitLab integration Merge request builds and commit status in GitLab.

A TeamCity installation has one server and any number of build agents. The server holds the configuration, the build queue, history and artifacts, and the web UI. Agents are separate machines or containers with the tools a build needs (SDKs, Docker, browsers); each agent runs one build at a time and reports its environment to the server. When a build is queued, the server assigns it to a compatible idle agent. Cloud profiles can start agents on demand in AWS, Azure, Google Cloud, Kubernetes and other environments and stop them when idle. JetBrains also offers TeamCity Cloud, a hosted server, alongside the on-premises product.

Configuration is organized in a tree of projects. A project contains subprojects, build configurations, VCS roots, templates, parameters and connections, and children inherit from their parents. For OrdersPortal, a project OrdersPortal might contain build configurations Build API, Build Web, Integration Tests and Deploy Staging.

The flow of one change is: a commit lands in GitLab, the VCS trigger on a build configuration notices it, the server queues a build, a matching agent checks out the code and runs the steps, publishes artifacts and test results, and the server reports the result back to GitLab.

Pitfalls:

  • Building on the server machine. Run builds on agents only; the server should stay responsive and free of build tooling.
  • Snowflake agents. Hand-configured agents drift. Build agents from images (the official agent Docker images or your own) so every agent of a kind is identical.

A build configuration is one kind of build: its VCS roots, build steps, triggers, failure conditions, artifact rules, agent requirements and build features. Build steps use runners: the command line runner, .NET, Gradle, Maven, Node.js, Docker, Kotlin script and others. Steps run in order on the same agent and share the checkout directory.

Triggers start builds automatically: the VCS trigger on new commits, the schedule trigger on cron-like schedules, and the finish build trigger after another configuration completes. Artifact rules such as publish => orders-api.zip tell TeamCity which files to keep and how to package them. Agent requirements restrict which agents can run the configuration, for example teamcity.agent.jvm.os.name contains Linux or “Docker is present”; TeamCity also adds implicit requirements when a step references a parameter that only some agents define. Failure conditions can fail a build on test failures, on a metric changing (such as code coverage or artifact size), or on specific text in the log.

TeamCity’s test reporting is a strength: it tracks tests across builds, flags new failures versus known ones, detects flaky tests, and can mute a test with an investigation assigned so a known failure stops blocking unrelated work.

Pitfalls:

  • One giant build configuration. A single configuration that builds, tests, packages and deploys cannot reuse parts or run them in parallel. Split it and connect the pieces with a build chain.
  • Steps that depend on state left by earlier builds. Agents reuse checkout directories for speed; make steps idempotent or clean what they need.

A VCS root describes a repository: its fetch URL, the default branch, the branch specification (which other branches to monitor), and authentication. Several build configurations can share one VCS root. For Git, TeamCity supports HTTPS and SSH URLs; authenticate with an access token, an uploaded SSH key or a configured connection (such as a GitLab connection) rather than a personal password.

The branch specification uses +: and -: rules with wildcards, for example +:refs/heads/* to include all branches and -:refs/heads/sandbox to exclude one. The default branch is always included. A build configuration can narrow the root’s branches further with a branch filter, which is useful when one root serves several configurations with different needs.

// Kotlin DSL - not compiled here
object OrdersPortalRepo : GitVcsRoot({
name = "OrdersPortal"
url = "https://gitlab.example.test/orders/ordersportal.git"
branch = "refs/heads/main"
branchSpec = """
+:refs/heads/*
-:refs/heads/sandbox
""".trimIndent()
authMethod = password {
userName = "oauth2"
password = "credentialsJSON:00000000-0000-0000-0000-000000000000"
}
})

The credentialsJSON: value is a token reference that TeamCity creates when you store a secure value in the project; the actual token never appears in the DSL. Branch specifications must not overlap with merge request branches handled by the Pull Requests feature (see GitLab integration).

Pitfalls:

  • Monitoring every branch with an expensive configuration. A full integration suite on every push to every branch saturates agents. Monitor main and release branches broadly, and handle feature work through merge request builds.
  • Committing real tokens in DSL files. Use secure parameters and credentialsJSON references.

Parameters are name=value pairs that you reference with %name% anywhere in settings and build scripts. TeamCity has three types:

  • Configuration parameters (no prefix, for example %api.url%) customize settings and are not passed to the build process unless referenced.
  • Environment variables start with env. (env.ASPNETCORE_ENVIRONMENT) and are passed to the build process as environment variables.
  • System properties start with system. and are passed to build tools that support them, such as -D properties for Maven, Gradle and Ant.

TeamCity also predefines many parameters, such as %teamcity.build.branch% and %build.number%. Values come from several sources with a defined priority: from highest, an enforced settings template, the Run custom build dialog, the build configuration, the project (inherited by subprojects), a regular template, and the agent’s buildAgent.properties. A build step can change a parameter for the rest of the build with the service message ##teamcity[setParameter name='...' value='...'].

Parameters can be typed: a text field with validation, a checkbox, a select list or a password. Password parameters hold secrets; their values are masked in the UI and build logs and appear in DSL only as credentialsJSON: references.

// Kotlin DSL - not compiled here
params {
param("api.url", "https://api.staging.example.test")
param("env.ASPNETCORE_ENVIRONMENT", "Staging")
select("deploy.target", "staging", options = listOf("staging", "production"))
password("env.ORDERS_DB_PASSWORD", "credentialsJSON:11111111-1111-1111-1111-111111111111")
}
Terminal window
# A command line step using the parameters above
echo "Branch: %teamcity.build.branch%"
echo "Deploying to %deploy.target% using %api.url%"

A reference to a parameter that does not exist anywhere becomes an implicit agent requirement, so a typo can leave a build waiting forever for an agent that defines it. To write a literal percent sign, double it (%%).

Pitfalls:

  • Secrets in plain configuration parameters. They show in the UI and logs. Use password parameters.
  • Overriding at too many levels. When a value is set on the project, a template and the configuration, finding the effective value is hard. Set each parameter at one level.

A build configuration template holds settings that several build configurations share: steps, parameters, triggers, features, requirements. Configurations based on a template inherit its settings and can add their own or override parameters; changing the template changes all of them. A configuration can be attached to several templates, a project can define a default template that applies to all its configurations, and an enforced settings template (assigned to a project by a system administrator) applies settings that child configurations cannot disable or override, which is how an organization enforces, for example, a mandatory security scan step.

// Kotlin DSL - not compiled here
object DotnetServiceTemplate : Template({
name = "Dotnet service"
params {
param("service.project", "")
}
steps {
script {
name = "Restore and test"
scriptContent = "dotnet test %service.project%"
}
script {
name = "Publish"
scriptContent = "dotnet publish %service.project% -c Release -o publish"
}
}
artifactRules = "publish => service.zip"
})
object BuildApi : BuildType({
templates(DotnetServiceTemplate)
name = "Build API"
params {
param("service.project", "src/Orders.Api")
}
})

In the Kotlin DSL, plain Kotlin functions and classes are an alternative to templates: a function that adds the standard steps to any BuildType is reusable, testable and visible in code review. Many teams use DSL code for reuse within a repository and templates for settings managed centrally.

Pitfalls:

  • Template changes with no review. A template edit in the UI changes dozens of builds at once. Keep templates in versioned settings.
  • Deep inheritance. A template on a template on a default template makes the effective configuration hard to reason about. Keep it shallow.

Versioned settings store a project’s configuration in a repository, either as XML or as a Kotlin DSL in a .teamcity folder. With the Kotlin DSL, configuration changes go through merge requests like application code, can be generated with loops and functions, and can be validated locally. TeamCity can apply settings from the repository and, if allowed, commit UI changes back.

A settings.kts file declares the configs version (the TeamCity version whose settings format the code targets; TeamCity writes it when it generates the DSL and uses it to transform older code on upgrade) and the project:

// .teamcity/settings.kts - not compiled here
import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script
import jetbrains.buildServer.configs.kotlin.triggers.vcs
import jetbrains.buildServer.configs.kotlin.vcs.GitVcsRoot
version = "2025.11"
project {
vcsRoot(OrdersPortalRepo)
template(DotnetServiceTemplate)
buildType(BuildApi)
buildType(BuildWeb)
buildType(DeployStaging)
}
object BuildWeb : BuildType({
name = "Build Web"
vcs { root(OrdersPortalRepo) }
steps {
script {
name = "Install and build"
scriptContent = "npm ci && npm run build"
}
}
triggers { vcs { } }
artifactRules = "dist => web.zip"
})

Use the package names without a DSL API version (jetbrains.buildServer.configs.kotlin), which TeamCity recommends since 2022.04, and when the server is upgraded, follow the “Update DSL from …” notes in the upgrade guide. Keep the version value TeamCity generated for your server unless that guide tells you to change it.

The security note in TeamCity’s documentation applies here: if untrusted users can open merge requests, building their changes can run code they wrote, including modified .teamcity settings. Do not start such builds automatically; build them manually after review or configure untrusted builds.

Pitfalls:

  • Mixing UI edits and DSL edits. Decide whether the UI may change versioned settings; otherwise UI changes are lost or create conflicts.
  • Copy-pasted DSL. The point of Kotlin is reuse. Extract functions or templates when two build types share steps.

A build chain is a set of build configurations connected by snapshot dependencies. A snapshot dependency guarantees that the dependent build and its dependencies use the same source revision, and it lets TeamCity reuse a suitable finished build instead of running it again. Starting the last build in a chain queues the whole chain; builds without dependencies between them run in parallel on different agents.

Artifact dependencies pass files: Deploy Staging takes service.zip from the Build API build in the same chain, so the deployed package is exactly the one that was tested.

// Kotlin DSL - not compiled here
object DeployStaging : BuildType({
name = "Deploy Staging"
type = BuildTypeSettings.Type.DEPLOYMENT
dependencies {
snapshot(BuildApi) { }
snapshot(BuildWeb) { }
artifacts(BuildApi) {
buildRule = sameChainOrLastFinished()
artifactRules = "service.zip => deploy/"
}
}
steps {
script { scriptContent = "./deploy.sh staging deploy/service.zip" }
}
})

TeamCity 2025.07 introduced pipelines, a simpler, YAML-based alternative to build configurations and chains with a visual editor; they became generally available in 2026.2. A pipeline cannot be converted to build configurations or back, and some advanced build configuration features are still on the pipelines roadmap, so check that page before choosing pipelines for a large existing setup.

Pitfalls:

  • Rebuilding instead of reusing. Without snapshot dependencies, every downstream configuration re-runs its upstream builds or uses artifacts from a different commit.
  • Deploying artifacts from “last successful build”. That may be a different revision from what was tested. Take artifacts through the chain.

Three features connect TeamCity to GitLab:

  • VCS root or GitLab connection. A GitLab connection in the project lets TeamCity authenticate with GitLab and simplifies creating VCS roots and other features.
  • Pull Requests build feature with the GitLab hosting type. TeamCity detects merge requests and builds them on the refs/merge-requests/*/head branches. It authenticates with the VCS root’s credentials, a GitLab personal access token with api scope, or a refreshable token from a connection, and can filter by source or target branch. It only detects merge requests created after the feature is enabled. The Automatic Merge feature can merge requests whose builds succeed.
  • Commit Status Publisher build feature with the GitLab publisher. TeamCity posts the build status to the commit in GitLab as soon as the build is queued and updates it as the build progresses, so the merge request shows the TeamCity result. The GitLab API URL is optional; if it is empty, TeamCity derives it from the VCS root’s fetch URL. The project’s CI/CD (or Pipelines) feature must be enabled in GitLab for statuses to be shown.

With these in place, GitLab can require the TeamCity status before merging. If a team also uses GitLab CI/CD, decide which system owns which checks, so a merge request does not run the same tests twice.

Pitfalls:

  • Branch specification that also matches merge request refs. The Pull Requests feature extends the root’s branch specification; overlapping patterns cause duplicate or ambiguous builds.
  • Automatic builds of external merge requests. For public projects, require manual approval or untrusted builds.
You need Use
One kind of build with steps and triggers A build configuration
The same steps in many configurations A template, or a Kotlin function in the DSL
Settings that teams must not remove An enforced settings template
Configuration reviewed in merge requests Versioned settings with the Kotlin DSL
Several builds on the same revision, reusing results A build chain with snapshot dependencies
A simpler, visual setup for a new project TeamCity pipelines
Results visible in GitLab merge requests Pull Requests feature plus Commit Status Publisher

What are the three TeamCity parameter types? Configuration parameters (no prefix) used within TeamCity settings, environment variables (env. prefix) passed to the build process, and system properties (system. prefix) passed to build tools that support them.

What does a snapshot dependency guarantee? That the dependent build and its dependencies run on the same source revision, with TeamCity reusing suitable existing builds where it can.

Why might a build stay queued with no compatible agents? Its agent requirements, explicit or implicit, match no agent. A common cause is a reference to an undefined parameter, which TeamCity turns into an implicit requirement.

How does TeamCity report build results to a GitLab merge request? The Commit Status Publisher build feature with the GitLab publisher posts commit statuses through the GitLab API; the Pull Requests feature makes TeamCity build the merge request refs.

Senior scenario: OrdersPortal’s TeamCity has 80 hand-edited build configurations, frequent “works on agent 3 only” failures and no record of who changed what. How do you fix it? Move the projects to versioned settings with the Kotlin DSL, generated from the current configuration, and require merge requests for changes. Extract the shared steps into Kotlin functions or a small number of templates, and add an enforced template for mandatory checks. Rebuild agents from images with pinned tool versions and explicit requirements, and use build chains with snapshot and artifact dependencies so deploys use tested artifacts. Track agent-specific failures to retire the drifted machines.