TeamCity On-Premises 2024.07 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 of version 1.3.70 or later must be installed as an agent tool to run this step.

Kotlin Script 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.7.3") 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

Additional JVM command line parameters allow you to set initial and maximum heap sizes, enable additional logging, select the required bytecode verifier mode, and more.

You can specify both standard (begin with -, for instance -verbose:[class|module|gc|jni] or --dry-run) and non-standard (begin with -X, for instance -Xmx<size> or -XstartOnFirstThread) JVM options.

To specify multiple command line parameters, use space as a separator. For example:

-verbose:gc -Xdiag -Xcomp -Xmx512m -Xms256m
Last modified: 19 September 2023