TeamCity 2019.1 Help

Upgrading DSL

On this page:

The TeamCity XML settings format is usually changed in the major releases. During the first start after the server update, TeamCity converts XML settings files in the TeamCity Data directory to the new format.
When settings are stored in Kotlin DSL, the Kotlin code might need to be changed to be still functional. It is also recommended to update the Kotlin code to the latest config version with each version.
These recommendations are displayed as server health reports on the corresponding pages of the server administration UI.

TeamCity settings format changes

As far as the DSL is concerned, there are the following types of TeamCity settings changes.

Changes which can be performed automatically

These types of settings changes do not require changing the Kotlin DSL as the changes are applied by the server automatically on each settings regeneration from the DSL. It is recommended though to update the DSL to a newer configs version to reduce performance hit and make Kotlin scripts closer to the settings you see in the UI.
A lot of changes in TeamCity settings fall into this category. For example, some plugin implementing a build step may rename its parameters. The DSL from the previous TeamCity version generates a parameter with the old name, but TeamCity can automatically replace the old parameter name with the new one after DSL execution.

Changes which cannot be performed automatically

Some TeamCity settings changes require external information and cannot be performed automatically. For example, in TeamCity 10.0 the settings of the cloud integration were stored in a dedicated file which was not committed to a VCS. In TeamCity 2017.1 these settings were moved to the project level. TeamCity cannot perform such a transformation of settings automatically without external data,so manual DSL code update is required.

Versions in DSL code

Kotlin DSL API version

This is the version included in the Kotlin DSL API package name: jetbrains.buildServer.configs.kotlin.v2018_2. New backward-incompatible API will be provided in a new package and the API from older versions will continue to work.

Configs version

This is the version specified in settings.kts, it looks like this:

version = "2019.1" project(Some_Project)

TeamCity uses this version to perform transformations DSL execution to make settings up-to-date.
For instance, your DSL scripts could be generated by TeamCity 2017.2 and have the version set to "2017.2". When you upgrade your server to version 2019.1, TeamCity will execute your DSL and apply additional transformations to modify the settings according to the format expected by version 2019.1.

DSL upgrade procedure

After a TeamCity upgrade, the versioned settings are disabled globally on the whole TeamCity server, and a corresponding health report is shown in the administration UI. This is done to prevent TeamCity from changing the settings in the version control if you upgrade a non-production copy of the TeamCity server.

If the server is a production installation, enable versioned settings using the action in the health report. This will make TeamCity commit converted XML file to the VCS. For settings in Kotlin format the files inside plugin-settings directory and meta-runners will be committed.

At this point, the version control has the previous version of Kotlin DSL scripts.

If some of the settings conversions cannot be applied automatically, TeamCity will disable the versioned settings for the affected projects and a corresponding health report is shown. You should update the DSL as per the notes below and then the versioned settings can be enabled in the project.

For the projects with settings in Kotlin DSL which were not affected by the settings conversions or if the settings can be converted automatically, the Kotlin DSL scripts do not require any immediate changes and you can continue using the projects as usual (versioned settings stay enabled in such projects). However, it is recommended to update the Kotlin scripts to the up-to-date configs version. TeamCity displays a health report for each affected project with instructions on how to update DSL. In order to check if DSL code update is required, load the settings from VCS and see the Current status on the Versioned settings tab: it will show a warning if update is required.

Update DSL from 2018.2.x to 2019.1.x

This release introduces the new DSL API version, v2019_1, but its package is still jetbrains.buildServer.configs.kotlin.v2018_2 because there were no significant changes in the DSL between versions 2018.2.x and 2019.1.x.

Updating Maven build steps

The DSL producing Maven build steps should be updated. If a Maven build step did not have the useOwnLocalRepo parameter set to true, the following localRepoScope parameter should be added:

maven { ... localRepoScope = MavenBuildStep.RepositoryScope.MAVEN_DEFAULT }

If useOwnLocalRepo was set to true, then it should be replaced with:

maven { ... localRepoScope = MavenBuildStep.RepositoryScope.BUILD_CONFIGURATION }

Add version to MSBuild and VS.Solution build steps

If MSBuild or VS.Solution build steps have the parameter toolsVersion set to MSBuildStep.MSBuildToolsVersion.V15_0, theadditional version = MSBuildStep.MSBuildVersion.V15_0 parameter should be added:

msBuild { ... toolsVersion = MSBuildStep.MSBuildToolsVersion.V15_0 version = MSBuildStep.MSBuildVersion.V15_0 }

Build configuration parameter buildDefaultBranch is deprecated

The build configuration version control settings parameter buildDefaultBranch is deprecated: branchFilter should be used instead.
For instance, if buildDefaultBranch was set to false, the following branch filter should be specified instead:

vcs { branchFilter = """ +:* -:<default> """ }

Update DSL from 2018.1.x to 2018.2.x

This release introduces the new DSL API version, v2018_2, its package is jetbrains.buildServer.configs.kotlin.v2018_2.

Update DSL from 2017.2.x to 2018.1.x

This release introduces the new DSL API version, v2018_1, its package is jetbrains.buildServer.configs.kotlin.v2018_1. The previous API versions work and you can keep using them if you don't want to use portable DSL scripts.

Updating Docker parameters

If you used Kotlin DSL with TeamCity 2017.2 for Docker plugin configurations, you may need to perform some changes in your Kotlin configuration scripts to make your code compatible with TeamCity 2018.1.

The essence of the changes:

  • build step dockerBuild is now converted to dockerCommand

  • the parameters for DockerBuild are now sub-parameter for commandType selector

Note the difference:

Docker Build 2 Docker Command migration
# DockerBuild in 2017.2: dockerBuild { name = "name of the build step" source = content { content = """ FROM busybox MAINTAINER KIR <kir@maxkir.com> """.trimIndent() } namesAndTags = "maxkir/maxkir_test" } #---------------------------------------- # DockerBuild in 2018.1: dockerCommand { name = "name of the build step" commandType = build { source = content { content = """ FROM busybox MAINTAINER KIR <kir@maxkir.com> """.trimIndent() } namesAndTags = "maxkir/maxkir_test" } }

Docker push command support

dockerCommand { name = "name of the push step" commandType = push { namesAndTags = "maxkir/maxkir_test" } }

Adding label property to Gerrit publisher settings in Commit Status Publisher

Since TeamCity 2018.1 Gerrit publisher settings in the Commit Status Publisher build feature allow customising the Gerrit label that reflects the build status, i.e. now you can use something other than Verified.

To manually modify Kotlin DSL settings, the label = "Verified" statement must be added as follows:

features { ... commitStatusPublisher { publisher = gerrit { server = "<server>" gerritProject = "<project>" failureVote = "-1" successVote = "+1" userName = "<user>" uploadedKey = "<key>" label = "Verified" // the statement to be added } } ... }

Update DSL from 2017.1.x to 2017.2.x

DSL version

This release introduces the new DSL API version, v2017_2. The previous API version works and you can keep using it if you do not need the features provided by the new API.

If you used 2017.2 EAPs and tested changing DSL settings via the UI, you need to apply all the UI patches created by TeamCity before upgrading as some API is changed in an incompatible way.

The current package name for the settings generated by TeamCity is jetbrains.buildServer.configs.kotlin.v2017_2.

With the new API, you can benefit from a number of new features, including the editable administration UI for Kotlin DSL projects and DSL documentation. To use them for your existing project, your .kt files should be switched to packages from the v2017_2 version.

  • To compile this project, you also need to update your pom.xml. The easiest way is to invoke the Download settings in Kotlin format action in your project and copy the pom.xml from the generated zip archive. Alternatively you can update pom.xml yourself with the following:
    • change teamcity.dsl.version to: <teamcity.dsl.version>2017.2</teamcity.dsl.version>

    • change the kotlin version to: <kotlin.version>1.1.4-3</kotlin.version> and add a dependency on kotlin-runtime and kotlin-reflect:

<dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-runtime</artifactId> <version>${kotlin.version}</version> <scope>compile</scope> </dependency> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-reflect</artifactId> <version>${kotlin.version}</version> <scope>compile</scope> </dependency>

Once you switch the project to new API and check in the changes, TeamCity will detect and apply them and after that web UI editing will be enabled.
To use the new DSL API in a repository with an existing pom.xml, the maven dependency version has to be updated to 2017.2.

Updating Docker parameters

If you used Kotlin DSL with TeamCity 2017.1 for Docker plugin configurations, you may need to perform some changes in your kotlin configuration scripts to make your code compatible with TeamCity 2017.2. Basically, TeamCity provides a converter for Kotlin configuration scripts to perform those changes automatically, but if it does not work due to some reason, the following changes need to be made manually:

  • rename the build runner step with the Docker Build runType to DockerBuild

  • rename the build runner step with the Docker Compose runType to DockerCompose

  • rename the docker-compose.file build parameter to dockerCompose.file

Starting from TeamCity 2017.2, the Docker plugin has its own typed DSL for the Docker build feature, Docker Wrapper, Docker, and Docker Compose runners.

Docker Compose and Docker Build
steps { dockerCompose { name = "Start services" file = "db-tests/scripts/docker-compose.yml" } dockerBuild { name = "Docker build step" source = path { path = "some/context/Dockerfile" } // Case for Dockerfile specified by an URL: //source = url { // url = "https://raw.githubusercontent.com/JetBrains/teamcity-docker-minimal-agent/master/ubuntu/Dockerfile" //} // Case for Dockerfile specified by text: //source = content { // content = """ // FROM busybox // MAINTAINER Kirill Maximov <kir@jetbrains.com> // """.trimIndent() //} contextDir = "some/context" namesAndTags = "my:tag" } }
Docker Build Feature
features { dockerSupport { cleanupPushedImages = true loginToRegistry = on { dockerRegistryId = "PROJECT_EXT_2" } } }
Command Line runner with Docker Wrapper
script { scriptContent = "ls -lR" dockerImage = "openjdk:8u121" dockerPull = true dockerRunParameters = "--rm -v /some/path:/another/path:ro" }

Updating default project template

Since 2017.2 EAP3, TeamCity supports default templates in projects. This setting was stored in a project feature of the "DefaultTemplate" type in EAP3 and EAP4, but since 2017.2 RC the project configuration schema was changed to accommodate for default templates.
To manually convert a DSL project configuration that employs the default template, you will have to delete a corresponding project feature and replace it with the defaultTemplate property assignment as follows:

2017.2 EAP3/4 DSL project configuration with a default template configured:

object Project : Project({ uuid = "2b241ffb-9019-4e60-9a3a-d5475ab1f312" extId = "ExampleProject" parentId = "_Root" name = "Example Project" ... features { ... feature { id = "PROJECT_EXT_4" type = "DefaultTemplate" param("template", "ExampleProject_MyDefaultTemplate") } ... } ... })

2017.2 DSL project configuration with the default template configured:

object Project : Project({ uuid = "2b241ffb-9019-4e60-9a3a-d5475ab1f312" extId = "ExampleProject" parentId = "_Root" name = "Example Project" defaultTemplate = "ExampleProject_MyDefaultTemplate" ... features { ... } ... })

Updating .NET CLI parameters

Since 2017.2 TeamCity bundles .NET CLI plugin. If you were using Kotlin DSL for the plugin parameters in TeamCity 2017.1.x, you need to change the commands as follows. In TeamCity 2017.1.x:

steps { step { type = "dotnet" param("dotnet-command", "build") param("dotnet-paths", "WindowsAzure.sln") } }

Since TeamCity 2017.2 you could explicitly specify build steps with parameters:

steps { dotnetBuild { projects = "WindowsAzure.sln" } }

Common parameters

2017.1

2017.2

Comment

dotnet-command

dotnet<Command>

Now the command name reflects the build step name, e.g. dotnetRestore

dotnet-args

args

dotnet-verbosity

logging

dotnet build

2017.1

2017.2

Comment

dotnet-paths

projects

dotnet-build-config

configuration

dotnet-build-framework

framework

dotnet-build-output

outputDir

dotnet-build-runtime

runtime

dotnet-build-no-deps

-

Should be added as the --no-dependencies argument

dotnet-build-not-incremental

-

Should be added as the --no-incremental argument

dotnet clean

2017.1

2017.2

dotnet-paths

projects

dotnet-clean-config

configuration

dotnet-clean-framework

framework

dotnet-clean-output

outputDir

dotnet-clean-runtime

runtime

dotnet msbuild

2017.1

2017.2

dotnet-paths

projects

dotnet-msbuild-config

configuration

dotnet-msbuild-platform

platform

dotnet-msbuild-targets

targets

dotnet-msbuild-runtime

runtime

dotnet nuget delete

2017.1

2017.2

dotnet-nuget-delete-id

packageId

dotnet-nuget-push-source /

dotnet-nuget-delete-source

packageSource

secure:dotnet-nuget-delete-api-key

apiKey

dotnet nuget push

2017.1

2017.2

Comment

dotnet-paths

packages

dotnet-nuget-push-source

packageSource

dotnet-nuget-push-no-symbols

noSymbols

secure:dotnet-nuget-push-api-key

outputDir

dotnet-build-runtime

apiKey

dotnet-nuget-push-no-buffer

-

Should be added as the --disable-buffering true argument

dotnet pack

2017.1

2017.2

Comment

dotnet-paths

projects

dotnet-pack-config

configuration

dotnet-pack-runtime

runtime

dotnet-pack-no-build

skipBuild

dotnet-pack-output

outputDir

dotnet-pack-version-suffix

versionSuffix

dotnet-pack-serviceable

-

Should be added as the --serviceable argument

dotnet publish

2017.1

2017.2

dotnet-paths

projects

dotnet-publish-config

configuration

dotnet-publish-framework

framework

dotnet-publish-output

outputDir

dotnet-publish-runtime

runtime

dotnet-publish-version-suffix

versionSuffix

dotnet restore

2017.1

2017.2

Comment

dotnet-paths

projects

dotnet-restore-config

configFile

dotnet-restore-runtime

runtime

dotnet-restore-packages

packagesDir

dotnet-restore-source

packageSources

dotnet-restore-ignore-failed

-

Should be added as the --ignore-failed-sources argument

dotnet-restore-no-cache

-

Should be added as the --no-cache argument

dotnet-restore-parallel

-

Should be added as the --disable-parallel argument

dotnet-restore-root-project

-

Should be added as the --no-dependencies argument

dotnet run

2017.1

2017.2

dotnet-paths

projects

dotnet-run-config

configuration

dotnet-run-framework

framework

dotnet-run-runtime

runtime

dotnet test

2017.1

2017.2

dotnet-paths

projects

dotnet-test-config

configuration

dotnet-test-framework

framework

dotnet-test-no-build

skipBuild

dotnet-test-output

outputDir

dotnet-test-settings-file

settingsFile

dotnet-test-runtime

runtime

dotnet-test-test-case-filter

filter

dotnet vstest

2017.1

2017.2

Comment

dotnet-paths

assemblies

dotnet-vstest-config-file

settingsFile

dotnet-vstest-framework

framework

dotnet-vstest-platform

platform

dotnet-vstest-filter-type

filter

To filter tests by name, use name { names = "..." }; for the test case filter, use filter { filter = "..." }

dotnet-vstest-is-isolation

-

Should be added as the /InIsolation argument

Update DSL from 10.0.x to 2017.1.x

TeamCity 2017.1 does not introduce a new Kotlin DSL API, the same package as in TeamCity 10.0.x is used (jetbrains.buildServer.configs.kotlin.v10). Several new properties were added to the existing API; to get the latest API for the scripts development, update teamcity.dsl.version in pom.xml to the 2017.1-SNAPSHOT for EAP builds and to the 2017.1 for release builds.

Changes requiring manual Kotlin DSL scripts update

These changes should be performed before enabling versioned settings in the projects where they were disabled on TeamCity upgrade with the message: "Versioned settings are disabled in this project because its settings files were modified during TeamCity upgrade".

Converting cloud profiles

This is only relevant if you use Kotlin DSL for the Root project settings and have cloud profiles.
In 2017.1 cloud profiles were moved from the server level to the Root project level. Since they were not defined in the Kotlin DSL, in case you enable the versioned settings the existing cloud profiles will be deleted form he server. Thus before continuing to use Kotlin DSL fr the root project on the server make sure to add the cloud profiles definitions to the root project settings in Kotlin DSL.

To update your settings with the cloud profile information, perform the following:

  1. Run the 'Download settings in Kotlin format' action in the Root project and save the zip with the generated DSL

  2. Copy project features of type CloudIntegration and CloudProfile from the .teamcity/_Root/Project.kt file to the root project config in your settings

  3. Commit your changes to the VCS

  4. Enable versioned settings on the Versioned Settings tab of the Root project.

Names in entities

Due to the fix of issue TW-48609, if your settings contain nameless entities, TeamCity will report corresponding VCS settings errors. You need to manually set a name parameter to such entities to resolve the errors.

Updating Kotlin DSL configs version to 10.0 to 2017.1

The changes in this section should be done to Kotlin scripts on changing the scripts config version from 10.0 to 2017.1

Updating DotCover parameters

Parameters used by DotCover were changed and if you use them, make sure dotNetCoverage.tool has the dotcover value. If the dotNetCoverage.dotCover.home.path parameter is missing, set it to %teamcity.tool.JetBrains.dotCover.CommandLineTools.bundled%. The result should look like this:

param("dotNetCoverage.tool", "dotcover") param("dotNetCoverage.dotCover.home.path", "%teamcity.tool.JetBrains.dotCover.CommandLineTools.bundled%")

If you use DotCover with custom path (for example, /custom/path), then the result should look like this:

param("dotNetCoverage.tool", "dotcover") param("dotNetCoverage.dotCover.home.path", "/custom/path")

Updating Maven build step parameters

If you use a typed maven DSL without raw parameters, then this change should not affect you, because typed DSL generates up-to-date settings.

If you specify maven build runner settings via the param("name", "value") method, then parameters need to be updated. The easiest way to update settings is to switch to the typed DSL: you can generate settings in the Kotlin format to see what the typed DSL for Maven looks like.

If you want to continue using the param("name", "value") method, do the following:

  • rename the mavenSelection parameter to maven.path, change its old value to the new one:

Old value to be changed

New value

mavenSelection:bundledM2%teamcity.tool.maven%
mavenSelection:bundledM3_0%teamcity.tool.maven3%
mavenSelection:bundledM3_1%teamcity.tool.maven3_1%
mavenSelection:bundledM3_2%teamcity.tool.maven3_2%
mavenSelection:bundledM3_3%teamcity.tool.maven3_3%
mavenSelection:default%teamcity.tool.maven.AUTO%
mavenSelection:custom

value of the maven.home parameter

  • remove the maven.home parameter.

Updating PowerShell build step parameters

TeamCity 2017.1 adds support for cross-platform PowerShell. Previously PowerShell builds used only the Desktop edition and were run only on Windows.

To ensure that the existing builds remain restricted to the Desktop edition of PowerShell, set the following property in the existing PowerShell steps:

edition = PowerShellStep.Edition.Desktop

or if you use raw parameters:

param("jetbrains_powershell_edition", "Desktop")
Last modified: 11 June 2019