TeamCity On-Premises 2021.1 Help

Kotlin Script

The Kotlin Script runner allows executing a Kotlin script on Windows, Linux, or macOS.

Refer to Configuring Build Steps for a description of common build steps' settings.


A Kotlin compiler version 1.3.70 or later must be installed as an agent tool to run this step. Kotlin 1.5.0 is already bundled with TeamCity.

Kotlin settings



Kotlin compiler

Select a compiler version: use the bundled or default version, or enter a custom path to the compiler, relative to the build checkout directory.

Script type

Choose one of the two options: enter a custom script body right inside the runner or specify a path to a Kotlin script file (.kts ).

Kotlin script

Available for the Custom Script type.

Enter a code of a Kotlin script.

To extend the script's functionality with external libraries, you can use annotation-based references to Maven dependencies. For example:

#!/usr/bin/env kotlin @file:Repository("") @file:DependsOn("org.jetbrains.kotlinx:kotlinx-html-jvm:0.6.11") import kotlinx.html.*; import*; import kotlinx.html.attributes.* val addressee = args.firstOrNull() ?: "World" print(createHTML().html { body { h1 { +"Hello, $address!" } } }) ...

See Kotlin Help for details.

Kotlin script file

Available for the Script File type.

Enter a path to the script file, relative to the build checkout directory.

To support annotation-based references, the provided file must have the .main.kts extension.

Script parameters

Enter the parameters of the script, as in the command line. Parameter references are supported.

For security reasons, we highly recommend that you avoid using parameter references directly inside scripts if these parameters represent secure values. You can pass such values via script parameters instead. For example, to pass a token value, add a new build parameter with the "Password" type, refer it in the runner’s Script parameters field:


and call it as an argument within the script:

val accessToken = args[0]

This way, you can reuse the token’s value anywhere in the script.

This practice will ensure that these values are available on the agent only during the build. Otherwise, if the parameters are specified directly inside the script, their resolved values will be stored on the agent machine as long as the script itself is stored, which might compromise the security of your data.


Select JDK to run the script:

  • Default: the path to JDK Home is read either from the JAVA_HOME environment variable on the agent machine, or from the env.JAVA_HOME property specified in the build agent configuration file ( ). If these values are not specified, TeamCity uses the Java Home of the build agent process itself.

  • Custom: enter a path to a JDK installed on the agent.

  • Select any installed version by number.

JVM command line parameters

Specify JVM command line parameters: for example, maximum heap size or parameters enabling remote debugging. These values are passed by the JVM used to run your build.


-Xmx512m -Xms256m
Last modified: 14 May 2021