Besides storing settings in version control in XML format, TeamCity also allows storing the settings in the DSL (based on the Kotlin language). Using the version control-stored DSL 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.
Note that once you enable storing of the settings in DSL, you no longer can use TeamCity UI to edit affected project's settings.
Also, all the security implications apply.
Check also our blog post series on Kotlin DSL.
On this page:
- Advantages of Kotlin DSL vs XML
- Getting Started with Kotlin DSL
- Working with Kotlin DSL
- Making Changes to Project Settings
- Applying Changes to TeamCity
- Common Problems
Advantages of Kotlin DSL vs XML
The Kotlin settings format provides higher level of abstraction, and better code reuse.
- Build configurations often share settings and need to be different in few aspects only. For example, when you need to test your software against different platforms, let's take an ORM framework to be tested against different databases, then the builds running tests are mostly the same, the only difference is the part configuring a database connection.With Kotlin, you can extract the common part and reuse it across all builds which ensures that the common part does not change and makes maintaining builds easier.
Kotlin also allows you to describe your setup in terms of your domain. For example, TeamCity provides generic requirements for build agents and you can define requirements specific to your installation:
then you can use them in a build configuration:
Getting Started with Kotlin DSL
Downloading Settings in Kotlin
To start working with Kotlin DSL, go to the project settings page, click the Actions menu and select Download settings in kotlin format. This will generate a
.zip archive with project settings which can be used in your sandbox project.
When you have familiarized yourself with Kotlin, you can use the Kotlin-based DSL for project settings in production.
Using Settings in Kotlin in Production
- Enable versioned settings for your project.
- Select kotlin as the format.
Commit the settings to your version control. Once the project is switched to Kotlin, editing of the project settings is disabled in the UI (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.
- 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
.teamcitydirectory. If this repository already had 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.
Working with Kotlin DSL
.teamcity folder contains a maven project consisting of
<Project External Id> directory with the
Project.kt files, as well as
vcsRoots subdirectories. If the project contains subprojects, they will be placed in the directories with corresponding names.
Opening Project in IDE
pom.xml in your favourite IDE and check that the URL of the
teamcity-server repository points to your TeamCity.
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.
settings.kts script is an entry point for defining a single TeamCity project. TeamCity looks for the
settings.kts file in a project directory and runs it if it is found, so the script name must not be changed and its package must be the same as the project's external id.
The script should contain a single call to the
project() function with a Project instance or an
init function as an argument, you can also specify both of them to refine the specified Project in the
This file contains the project definition.
Vcs roots, Build types, and Templates of this project must be registered inside the project using the
template() methods respectively.
Subprojects can be defined either in their own
settings.kts or by calling the
subProjects() method in this project.
As this is a Kotlin code, you are free to add conditions, loops, methods, classes, etc.
All TeamCity entities - project, build configuration, VCS root and template have a so-called uuid. The
uuid, it is considered a new entity by TeamCity. For instance, if the build configuration
s in your project and never changing them.
There is also the extId field which is mandatory. The
Making Changes to Project Settings
Once project is switched into the Kotlin DSL format, we recommend the following approach for changing the project settings:
Set up unit tests.
Create a dedicated project on your TeamCity server to run these unit tests.
Create a separate branch/repository and run tests on your changes there.
If the tests are green, merge the changes into the default settings branch.
Creating New Project
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.
Apply your changes as described in the section below.
Applying Changes to TeamCity
When you have made changes to your Kotlin DSL code, сommit your code into the
.teamcity directory containing your project settings.
TeamCity will apply the changes to configuration as follows:
- TeamCity will detect the commit, execute Kotlin DSL files and produce new configuration files. Since internally TeamCity operates with XML, TeamCity will execute DSL files in a secure sandbox to produce XML configuration files. These XML files then will be applied to the existing project.
- TeamCity will apply the new configuration files to the 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 and the error message will appear under the Versioned Setting tab in project settings.
- The builds will run with the new settings.
- 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.
- The Kotlin DSL is experimental, and the provided API may change in future versions.
New URL of Settings VCS Root
Problem: I changed the url of the VCS root where settings are stored in Kotlin and now TeamCity cannot find any settings in the repository at the new location.
- Fix the url in the Kotlin dsl in the version control and push the fix.
- Disable versioned settings to enable the UI.
- Fix the url in the VCS root in the UI.
- Enable versioned settings with same VCS root and the Kotlin format again, TeamCity will detect that the repository contains the .
teamcitydirectory and ask if you want to import settings.
- Choose to import settings.
Prior to TeamCity 2017.1
Problem: I do not not want the passwords to be committed to the VCS, even in a scrambled form.
Solution: You can move the passwords to the parent project whose settings are not committed to a VCS.
Problem: I want to change passwords after the settings have been generated.
Solution: The passwords will have to be scrambled manually using the following command in the maven project with settings:
Since TeamCity 2017.1
Solution: Use tokens instead of passwords
For projects with settings in
kotlin-based DSL with the option to store security data outside the VCS enabled, it is possible to use tokens instead of passwords. Tokens can be generated via the "Generate Token for password" action available in the Project -> Actions menu. This action can be useful when project settings are generated via DSL (because the UI is disabled in this case) or if someone wants to change the password not via the user interface, but via a commit into VCS.
For now passwords are not inheritable by projects hierarchy. If a setting in a project (a VCS root, OAuth connection, cloud profile) requires a password, the token generated for this password can be used in this project only. For instance, it is not possible to take a generated token and use it in a similar setting in a subproject. A new token should be generated in this case.