DSL for TeamCity project configuration

Up until this EAP there were three options to configure project settings in TeamCity: the straightforward way was via the web UI, and the other two were using the REST API or via XML files if the versioned settings feature is enabled.

In this EAP we introduce a new way - the ability to define settings programmatically using DSL based on the Kotlin language.

Kotlin-based DSL can be seen as evolution of the versioned settings: now you can define your configuration in the Kotlin language 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.

To get started with Kotlin DSL:


    Download the TeamCity-DSL plugin and install it as described here.

  2. Navigate to Versioned settings menu option for your project, enable Versioned settings for your project, select kotlin as the format and commit the settings to your version control. Once this is done, editing for the project via the TeamCity Web UI will be disabled.

After you commit settings to the VCS,  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.

Some important facts:

Example of a Project defined in Kotlin DSL:

object Project : KProject({
    uuid = "my_project_id" // uuid should be some constant, never changing string; it is important for preserving history, new id means new entity with new history
    parentId = "_Root" // id of the parent project
    name = "Example of DSL"

    val vcsRoot = vcsRoot {
        uuid = "my_vcs_root_id" 
        extId = "ExampleOfDSL_VcsRoot"
        type = "jetbrains.git" // other available types: svn, perforce, tfs, mercurial, starteam, cvs, vault-vcs
        name = "Example of DSL VCS Root"
        param("url", "<url to my git repository>")

    buildType {
        uuid = "my_build_type_id"
        extId = "ExampleOfDSL_Build"
        name = "Build"

        vcs {
             entry(vcsRoot) // thanks to Kotlin, here we can have static reference to project VCS root

        steps {
             step {
                  type = "Maven2"
                  param("goals", "clean test")

        options {
             buildNumberPattern = "%build.counter%"

        requirements {
             contains("teamcity.agent.jvm.os.name", "Linux")

Since this is essentially Kotlin code, you can do whatever you like, add conditions, loops, methods, classes, etc. Note that for your convenience methods buildType(), vcsRoot() and others not only accept some instance, they also return it as a result. In the example above you can see how vcsRoot instance can be reused in build configuration. 

All TeamCity entities - project, build configuration, VCS root and template have so called uuid. uuid is an identifier which can be used to uniquely distinguish this specific entity from others. If at some point entity receives new uuid, it is considered as a new entity by TeamCity. For instance, if build configuration uuid changes, 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 for project - if its uuid changes, project will loose its investigations and muted tests. We suggest to select some naming scheme for uuid in your project and never change them unless you really want to make TeamCity think that these are new entities.

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

Smart checking for changes interval

Traditionally TeamCity uses polling for detecting changes in VCS repositories. Polling is a highly reliable approach suitable in the majority of cases. Even if the TeamCity server was stopped for a while, with polling it can easily pickup all the changes made in repositories on the next startup.

But polling has one downside which becomes more and more important, as TeamCity installation grows. If there are many different VCS repositories configured in TeamCity, polling can impose significant load on both TeamCity server and VCS repository servers.

The alternative approach is to use the push model: various post commit hooks and web hooks. This approach is more scalable, but it cannot be used alone: if the TeamCity server is stopped, obviously all push notifications will be lost.

This is why we decided to implement a combined approach. Starting with this EAP, if a commit hook initiates the process of checking for changes for some VCS root in TeamCity, TeamCity will automatically increase checking for changes interval for this VCS root, assuming that this commit hook will now come to TeamCity on a regular basis. But, if so happens that TeamCity detects a change in this VCS root during regular polling, then the checking for changes interval will be reset to the initial value specified by the user when the VCS root was created. This is done for the case when a commit hook stopped working for some reason. If the TeamCity server was restarted, it will switch to polling for all of the VCS roots, till commit hooks start informing it about new commits.

Please refer to our documentation on commit hooks configuration in various VCS repositories. 

Project Configuration Export  

It is now possible to export configuration files for a project with its children as a zip archive to move it to a different TeamCity server. The Project Settings | Settings Export page allows exporting the config files for a project and its subprojects, as well as external dependencies, i.e. build configurations used in snapshot dependencies, templates used as well as vcs roots and all main settings (ssh keys, issue trackers, oauth connections etc...) defined in the parent project.  

The settings archive also contains a report.log file detailing the reasons for exporting external entities.

VCS hosting integrations

Support for Perforce Jobs

If you use Perforce jobs to label your commits,  the changes associated with jobs are now marked with a "wrench"  icon   in the TeamCity UI. Navigating to the icon opens a pop-up with the job information:


Refreshed web UI 

In this EAP projects and build configurations as well as collapse/expand actions received new icons. Overall, the UI boasts of a refreshed look and feel.

Cloud support

Flaky Test Detector

REST API enhancements

With the latest REST API version it is now possible to:

Bundled Tools updates

Other Improvements