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 online documentation is available on your local server, accessible via the link on the Versioned Settings project tab in the UI or by running the mvn -U dependency:sources command in the IDE. See an example.


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


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: