Gradle

The Gradle build runner runs Gradle projects.

To run builds with Gradle, Gradle 0.9-rc-1 or later must be installed on all the agent machines. Alternatively, if you use the Gradle wrapper, you need to have properly configured Gradle Wrapper scripts checked in to your Version Control.

The runner supports all Gradle build configurations, including build.gradle and build.gradle.kts.

Gradle Parameters

Option	Description
Gradle tasks	Specify Gradle task names separated by spaces. For example, `:myproject:clean :myproject:build` or `clean build`. If this field is left blank, the 'default' task is used. Note that TeamCity currently supports building Java projects with Gradle. Building Groovy, Scala, and other projects has not been tested.
Gradle build file	A path to the Gradle build file, relative to the working directory. If empty (default), Gradle uses own settings to determine it.
Incremental building	TeamCity can make use of the Gradle `:buildDependents` feature. If the Incremental building option is enabled, TeamCity will detect Gradle modules affected by changes in the build and start the `:buildDependents` command for them only. This will cause Gradle to fully build and test only the modules affected by changes.
Gradle home path	Specify here the path to the Gradle home directory (the parent of the `bin` directory). If not specified, TeamCity will use Gradle specified in the agent's `GRADLE_HOME` environment variable. If you don't have Gradle installed on agents, you can use a Gradle wrapper instead.
Additional Gradle command line parameters	Optionally, specify the space-separated list of command line parameters to be passed to Gradle.
Gradle Wrapper	If enabled, TeamCity will look for Gradle Wrapper scripts in the checkout directory, and launch the appropriate script with Gradle tasks and additional command line parameters specified in the fields above. In this case, Gradle specified in Gradle home path and Gradle installed on the agent are ignored.

Run Parameters

Option	Description
Debug	Selecting the Log debug messages checkbox is equivalent to adding the `-d` Gradle command-line parameter. Running Gradle with the `DEBUG` log level can potentially expose sensitive information in the build log (learn more in the Gradle documentation). Before enabling this mode, make sure that the log can be viewed only by trusted users.
Stacktrace	Selecting the Print stacktrace checkbox is equivalent to adding the `-s` Gradle command-line parameter.

Java Parameters

Option	Description
JDK	Select a JDK. This section details the available options. The default is `JAVA_HOME` environment variable or the agent's own Java.
JDK home path	The option is available when <Custom> is selected above. Use this field to specify the path to your custom JDK used to run the build. If the field is left blank, 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 (`buildAgent.properties`). If these values are not specified, TeamCity uses the Java home of the build agent process itself.
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

Option

Description

JDK

Select a JDK. This section details the available options. The default is JAVA_HOME environment variable or the agent's own Java.

JDK home path

The option is available when <Custom> is selected above. Use this field to specify the path to your custom JDK used to run the build. If the field is left blank, 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 (buildAgent.properties). If these values are not specified, TeamCity uses the Java home of the build agent process itself.

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

Build properties

In Gradle builds, TeamCity system properties are different from Java system properties.

Regular Java system properties can be accessed globally. Use the System.getProperty("my.property") or providers.systemProperty("my.property").get() methods to obtain these properties' values.
TeamCity system properties are written to the Project object when a build initializes. Therefore, TeamCity system properties can be accessed anywhere the Project is available (use project.hasProperty("property.name") to check whether the required property is available).

The recommended way to reference TeamCity system properties is as follows:

task printProperty {
    doLast {
        println "${teamcity['teamcity.build.id']}"
    }
}

tasks.register("printProperty") {
    doLast {
        val teamcity: Map<*,*> by project
        println("${teamcity["teamcity.build.id"]}")
    }
}

or if the system property's name is a legal name identifier (for example, system.myPropertyName = myPropertyValue):

task printProperty {
     doLast {
          println "$myPropertyName"
     }
}

tasks.register("printProperty") {
    doLast {
        val myPropertyName: String by project
        println("$myPropertyName")
    }
}

Docker Settings

In this section, you can specify a Docker image which will be used to run the build step.

Code Coverage

The Gradle build runner supports code coverage with based on the IDEA code coverage engine and JaCoCo.

Configuration Cache

Starting with version 2024.03, TeamCity Gradle runner supports configuration cache. This feature significantly improves build performance by caching the result of the configuration phase and reusing this cache in subsequent builds.

Configuration cache is enabled if either of the following is true:

The --configuration-cache parameter was added to the runner's Additional Gradle command line parameters field.
A gradle.properties file includes the org.gradle.configuration-cache=true (for Gradle 8.1+) or org.gradle.unsafe.configuration-cache=true (for older Gradle versions) line. This applies to both the project's gradle.properties file and the one in the GRADLE_USER_HOME directory.

Current Limitations and Known Issues

Gradle configuration caches may not work as expected in the following cases:

if virtual builds (those spawned during parallel testing or Matrix Build runs) run in a different order from when the caches were created. See this YouTrack ticket for more information: TW-86556.
if the Clean Checkout is enabled;
if a build step runs within a Docker or Podman container;
if Gradle ignores configuration cache problems.
if the list of additional command line arguments includes those unsupported by Gradle Tooling API (--daemon, --stop, and others).

Build parameters whose values always change from build to build (for example, build.id or build.number) will be loaded only on demand. You can still obtain values of these properties using direct references (for example, project.teamcity["build.number"]), but the findProperty() method (project.findProperty("build.number")) yields no results. If you need to call this method in your Gradle script, use the following workaround:

Create a new configuration parameter and map it to the affected parameter: MyBuildNumber=%build.number%.
Create a new system property and map it to your new configuration parameter: system.buildNumber = %MyBuildNumber%.
Use the ${findProperty}("buildNumber")} syntax to obtain a required value in your Gradle script.

Note that this workaround prevents your build configuration from reusing the configuration cache, so you may also want to disable it.

Last modified: 20 March 2024