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

TeamCity 2018.x Documentation

Documentation for Previous Versions


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.


  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.

  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 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.


Since TeamCity 2018.1, there is an option to generate portable DSL scripts. When the option is enabled, TeamCity generates a single .teamcity/settings.kts script defining a project hierarchy. All ids in portable scripts are relative to the project where versioned settings were enabled, they are expanded to the full id during DSL execution. In portable Portable DSL there is has no restriction on a directory name for project settings. All settings can be moved to a single file.
Since portable scripts don't do not contain absolute ids, they can be used several times on the same or different TeamCity servers.
Since there is no restriction on directory name for project settings, branching and merging configs becomes easier.