You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.


Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


To start working with Kotlin DSL, go to the project settings page, click the Actions menu and select Download settings in kotlin format, the option available since TeamCity 10.0.3. This will generate a .zip archive with project settings which can be used in your sandbox project.


  1. Enable versioned settings for your project.
  2. Select kotlin as the format.
  3. Commit the settings to your version control.  


    Prior to TeamCity 2017.2, as soon as a project is switched to Kotlin, editing of its settings is disabled in the UI (except a few pages: Versioned settings, Maven Settings, SSH keys and Meta-runners).  If you need to enable editing, switch versioned settings to XML format or disable versioned settings.

    Since TeamCity 2017.2, project and build configuration settings will be available for editing from the web UI. See details below in the section above.

  4. Once you apply the versioned settings to your project, TeamCity will generate necessary Kotlin files for this project and check them in to the specified repository under the .teamcity directory. If this repository already contains project settings in the XML format, they will be preserved, but TeamCity will no longer use them:  once you get familiar with Kotlin files, these xml files can be removed.


The easiest way to experiment with DSL in TeamCity 2017.2+ is to edit settings in UI and check the UI diff script generated by TeamCity.

DSL Documentation

Since TeamCity 2017.2 after Kotlin DSL is enabled for a project, the TeamCity server provides html documentation for the core DSL API as well as the API provided by installed TeamCity plugins. The documentation is The online documentation is available on your local server, accessible via the link on the 'Versioned  Versioned Settings' project  project tab in the UI or UI or by running the mvn -U dependency:sources command in the IDE.  See an example.

Working with Kotlin DSL

The .teamcity folder contains a maven project consisting of pom.xml file and  the <Project Id> directory with the settings.kts and Project.kt files, as well as buildTypes, pluginData, and vcsRoots subdirectories. If the project contains subprojects, they will be placed in the directories with corresponding names.


If the server url is correct and your TeamCity is up and running, all necessary dependencies will be resolved automatically and you can start working with Kotlin DSL right away.



The Since 2017.2 the TeamCity server does not use uses the pom.xml file ; it is to fetch required dependencies from the Maven repository; the file is also used by the IDE to download required dependencies and to provide code completion as well as detect compilation errors, so any changes you will make to this POM file won’t have any effect during the DSL settings application to the server. You can also delete this file.

Debugging Maven ‘generate’ Task

The pom.xml file provided for a Kotlin project has the 'generate' task, which can be used to generate TeamCity XML files locally from the Kotlin DSL files. Since TeamCity 2017.2 this task supports debugging. If you’re using IntelliJ IDEA, you can easily start debugging of a Maven task, see screenshot:


Ability to Use External Libraries

Since TeamCity 2017.2 You can now use external libraries in your Kotlin DSL code, which allows sharing code between different Kotlin DSL-based projects. To use an external library in your Kotlin DSL code, add a dependency on this library into the .teamcity/pom.xml file in the settings repository and commit this change so that TeamCity detects it. Then, before starting the generation process, the TeamCity server will fetch the necessary dependencies from the Maven repository, compile code with them, and then start  the settings generator. 

Essential Files


 Since TeamCity 2017.2 dedicated DSL code is provided for a set of new plugins bundled with TeamCity (Docker, .NET CLI) and coverage plugins. Here is typical DSL code for the Docker-Compose build step:


You can create a new project via DSL inside a parent project which already has uses settings in the Kotlin format. A new project can be added either in its own directory with settings.kts or using the subProject() method in the parent project. 




Prior to TeamCity 2017.2, no external resources are supported and since pom.xml is not used on the server, any libraries that you might want to add will be ignored during DSL processing. 

Since TeamCity 2017.2, it is possible to use external libraries in your Kotlin DSL code. See details belowthe section above.

TeamCity will apply the changes to  configuration as follows: 


Solution: Use tokens instead of passwords
Excerpt IncludeStoring Project Settings in Version ControlStoring Project Settings in Version Controlnopaneltrue


. Please refer to the related section.

How to read files in Kotlin DSL

Problem: I want to generate a TeamCity build configuration based on the data in some file residing in the VCS inside the .teamcity directory

Solution: TeamCity executes DSL with the .teamcity as a current directory, so files can be read using the paths relative to the .teamcity directory e.g. File("data/setup.xml"). Files outside of the .teamcity directory are not accessible to Kotlin DSL.