You are viewing the documentation of TeamCity 2018.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.


Getting Started with Kotlin DSL

The Kotlin tutorial helps The Kotlin tutorial helps you learn most Kotlin features in a few hours.


To open the Kotlin DSL project in IntelliJ IDEA, open the .teamcity/pom.xml file as a project. All necessary dependencies will be resolved automatically right away. If all dependencies have been resolved, no errors in red will be visible in the settings.kts.
If you already have an IntelliJ IDEA project and want to add Kotlin DSL module to it, see this section.

Editing Kotlin DSL

If you created an empty project, that’s what you’ll see in your IDE when you open settings.kts:



To get familiar with Kotlin API, see the online documentation on your local server, accessible via the link on the the Versioned Settings project  project tab in the UI or by running the the mvn -U dependency:sources command  command in the IDE. Refer to   See the documentation on the public TeamCity server as an an an example.

The documentation is generated in a separate Java process and might take several minutes to build after the server restart

You can also use the the Download settings in Kotlin format option  option from the project project Actions menu menu. For instance, you can find a project that defines some settings that you want to use in your Kotlin DSL project and use this "download" action to see what the DSL generated by TeamCity looks like.


Code Block
changeBuildType(RelativeId("SampleProject_Build")) { // this part finds the build configuration where the change has to be done  
    features {
        add {
            // this is the part which should be copied to a corresponding place of the settings.kts file
    features {         add {
            swabra {
                filesCleanup = Swabra.FilesCleanup.DISABLED

It is implied that you move the changes from the patch file to you settings.kts and delete the patch file. Patches generation allows smooth transition from editing settings via UI to Kotlin DSL.

Sharing Kotlin DSL Scripts


  • id is the absolute id of the project, the same id we'll see in browser address bar if we navigate to this project
  • parentId is the absolute id of a parent project where this project is attached
  • uuid is some unique sequence of characters.
    The uuid is


    a unique identifier which associates a project, build configuration or VCS root with its data. If the uuid is changed, then the data is lost. The only way to restore the data is to revert the uuid to the original value. On the other hand, the id of an entity can be changed freely, if the uuid remains the same. This is the main difference of the non-portable DSL format from portable. The portable format does not require specifying the uuid, but if it happened so that a build configuration lost its history, one has to reattach it again via the web interface. 


  • Note

    If the build history is important, it should be restored as soon as possible: after the deletion, there is a configurable timeout (5 days by default) before the builds of the deleted configuration are removed during the build history clean-up.

In case of non-portable DSL, patches are stored under the project patches directory of .teamcity:


Ability to Use External Libraries

Since TeamCity 2017.2 you You can 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 to 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. 

View DSL in UI 

There is an option in the UI to help those using Kotlin-based DSL. When viewing your build configuration settings in the UI, you can click View DSL in the sidebar: the DSL representation of the current configuration will be displayed and the setting being viewed (e.g. a build step, a trigger, dependencies) will be highlighted. To go back, click Edit in UI.

FAQ and Common Problems


Why portable DSL requires the same prefix for all IDs?

In TeamCity projects, templates, build configurations and VCS roots all have unique IDs. These IDs usually look like:

<parent project id>_<entity id>

Since these IDs must be unique, there cannot be two different entities in the system with the same ID. 

But one of the reasons why portable DSL is called portable is because the same settings.kts script can be used to generate settings for two different projects even on the same server.

In order to achieve this and overcome IDs uniqueness, TeamCity operates with relative IDs in portable DSL scripts. These relative IDs do not have parent project ID prefix in them. So when TeamCity generates portable Kotlin DSL scripts, it has to remove the parent project ID prefix from the IDs of all of the generated entities.

But this will not work if not all of the project entities have this prefix in their IDs. In this case the following error can be shown:

Build configuration id '<some id>' should have a prefix corresponding to its parent project id: '<parent project id>_'

To fix this problem, one should change the ID of the affected entity. If there are many such IDs, Bulk edit IDs project action can be used to change all of them at once.

How to Add .teamcity as a New Module to a Project?


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

Kotlin DSL API documentation is not initialized yet


  • app/dsl-documentation/index.html on our Teamcity server displays "Kotlin DSL API documentation is not initialized yet"
  •  OutOfMemoryError during TeamCity startup with `org.jetbrains.dokka` in stack trace

 Solution: set the internal property teamcity.kotlinConfigsDsl.docsGenerationXmx=768m 

Passwords-Related Questions



Administrator's Guide: Storing Project Settings in Version Control