Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 10.x and 2017.x Documentation


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.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

Kotlin DSL

Using DSL based on the Kotlin language enables you to define settings programmatically, without the need to use XML files. Since Kotlin is statically typed, you automatically receive the auto-completion feature in IntelliJ IDEA which makes discovery of available API options a much simpler task.

You need to enable version settings for your project, select kotlin as the format and commit the settings to your version control. 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 had project settings in the XML format, they will be preserved. TeamCity also adds a pom.xml file under the .teamcity directory. You can open this POM in your IntelliJ IDEA and start working with Kotlin DSL right away. All necessary dependencies will be resolved automatically.


Once the project is switched to Kotlin, editing of the project settings via the web UI is disabled (except a few pages: Versioned settings, Maven Settings, SSH keys and Meta-runners), as currently there is no way to propagate changes made via the web UI to Kotlin DSL files.

To enable editing, switch versioned settings to XML format.


Note that:

  • each time when you make a commit into .teamcity, TeamCity will execute Kotlin DSL files. Since internally TeamCity still operates with XML, the executed DSL files will produce a bunch of XML files. These XML files then will be applied to the existing project effectively changing its configuration. In case of any problems (compilation failures, runtime errors, etc), new changes will not be applied, and the current project settings will be preserved on the server.
  • The Kotlin script is executed on the server, and since this is a potentially dangerous operation, the script is executed in the sandbox. It cannot modify the file system except the place where it is executed, it cannot run other programs, cannot use reflection, and so on.
  • at this point Kotlin DSL is experimental, and the provided API may change significantly in future versions.

Example of a Project defined in Kotlin DSL:

This is essentially Kotlin code, so you are free to  add conditions, loops, methods, classes, etc. Note that for your convenience the methods buildType()vcsRoot() and others not only accept some instance,  but also return it as a result. In the example above you can see how the vcsRoot instance can be reused in the build configuration. 

All TeamCity entities - project, build configuration, VCS root and template have a so-called uuid. The uuid is an identifier which can be used to uniquely distinguish this specific entity from others. If at some point the entity receives a new uuid, it is considered a new entity by TeamCity. For instance, if the build configuration uuid changes, the builds history of this build configuration will become empty (if you change it back before cleanup, the history will be restored). The same rule applies to a project - if its uuid changes, the project will loose its investigations and muted tests. We suggest selecting some naming scheme for uuids in your project and never change them unless you really want to make TeamCity think that these are new entities.

There is also the extId field which is mandatory. The extId is the same as build configuration (or template) ID / vcs root ID, project ID in the web UI. It can be changed at any time. But be aware that some settings use it, for instance the extId can appear in dep. parameter references. If you change the extId, you should find all its occurrences in the current project and change them too.

  • No labels