This page is a reference for integrating Gradle with JetBrains TeamCity. TeamCity ships a built-in Gradle runner — no additional plugins are required to build Gradle projects.

The Gradle runner

When you create a project from a repository URL, TeamCity scans for build.gradle or build.gradle.kts files and offers a pre-configured Gradle build step. You can also add a Gradle step manually by selecting Gradle as the runner type.

Key runner settings

Setting Description

Tasks

Space-separated Gradle tasks to execute (e.g. clean build). Defaults to the project’s default task when blank.

Use Gradle Wrapper

When enabled, TeamCity launches the Wrapper script from the checkout directory. Enabled by default on auto-detected steps. Recommended for all projects.

Gradle Wrapper Path

Custom path to gradlew relative to the working directory. Only needed if the Wrapper is not at the repository root.

Build File

Relative path to build.gradle or build.gradle.kts. For Gradle 9.0+, use the -p flag in Additional Command Line Parameters instead.

Additional Command Line Parameters

Extra flags and project properties, e.g. --configuration-cache, -x test, -PmyProp=value, --scan.

Gradle Home

Path to a local Gradle installation. Ignored when the Wrapper is enabled. Falls back to the agent’s GRADLE_HOME environment variable.

Incremental Building

Detects changed modules via VCS and runs :buildDependents only for affected projects. Available for classic build configurations.

Debug / Stacktrace

Toggle -d or -s flags. Debug logging may expose sensitive information in the build log.

JDK

Select from environment variables (JDK_HOME, JAVA_HOME), an explicit path, or the agent’s default JDK.

JVM Parameters

Arguments passed to the JVM that runs Gradle, e.g. -Xmx2g.

Docker / Podman

Run the build step inside a container image. Requires a Docker or Podman connection configured at the project level.

Code Coverage

Built-in support for IntelliJ IDEA and JaCoCo coverage engines.

See the Gradle runner documentation for the full setting reference.

Minimal build configuration

Via the UI

  1. Create a project from a repository URL.

  2. TeamCity auto-detects a Gradle build step with clean build tasks and Wrapper usage.

  3. Confirm the detected step.

  4. Add a VCS Trigger (Build Configuration Settings → Triggers) so builds run on every push.

Via Kotlin DSL

TeamCity supports configuration as code using Kotlin DSL, stored in .teamcity/settings.kts in your repository:

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.gradle
import jetbrains.buildServer.configs.kotlin.triggers.vcs

version = "2025.11"

project {
    buildType(Build)
}

object Build : BuildType({
    name = "Build"

    vcs {
        root(DslContext.settingsRoot)
    }

    steps {
        gradle {
            tasks = "clean build"
            useGradleWrapper = true
        }
    }

    triggers {
        vcs {}
    }
})

Via YAML pipelines

jobs:
  Build:
    name: Build
    steps:
      - type: gradle
        name: Gradle Build
        tasks: clean build
        use-gradle-wrapper: "true"

Using the Gradle Wrapper

The Gradle runner’s Use Gradle Wrapper option (enabled by default on auto-detected steps) is the recommended way to invoke Gradle. With the Wrapper enabled, build agents need only a JDK — the correct Gradle distribution is downloaded and cached automatically.

If the Wrapper script is not at the repository root, set Gradle Wrapper Path to its location relative to the working directory.

Caching and performance

TeamCity build agents are typically long-lived, so the Gradle User Home (~/.gradle) is preserved between builds on the same agent. Downloaded dependencies, Wrapper distributions, and the local build cache persist automatically without additional configuration.

For distributed or cloud agents, consider:

  • A Gradle Remote Build Cache to share task outputs across agents.

  • A repository manager (Artifactory, Sonatype Nexus) to proxy external dependencies within your network.

  • The --configuration-cache flag (or org.gradle.configuration-cache=true in gradle.properties) to skip the configuration phase on repeated builds.

The configuration cache has known limitations with TeamCity’s parallel test features and clean checkout scenarios. See the Gradle runner documentation for details.

System properties and environment variables

TeamCity system properties (those prefixed with system.) are passed to Gradle as native project properties — the same mechanism as gradle.properties.

Access them in build.gradle[.kts]:

// Simple names (no dots) — available as top-level properties
println("Build number: $buildNumber")    // from system.buildNumber

// Names containing dots — use the project.ext map
val vcsNumber: String by project.ext     // from system.vcsNumber
// or:
project.findProperty("build.vcs.number.1")

TeamCity also exposes env. parameters as environment variables on the agent. These can be read in Gradle via System.getenv("ENV_VAR_NAME") or providers.environmentVariable("ENV_VAR_NAME").

Publishing Build Scans

Add --scan to the Additional Command Line Parameters field (or to the gradleParams DSL property) to publish a Build Scan® for every build.

For richer integration, install the TeamCity Build Scan plugin. With the plugin installed, Build Scan links appear directly in the Build Results view rather than only in the build log.

To auto-accept the terms of use in CI without --scan, configure the Develocity plugin in settings.gradle[.kts]:

plugins {
    id("com.gradle.develocity") version "3.18.1"
}

develocity {
    buildScan {
        termsOfUseUrl = "https://gradle.com/help/legal-terms-of-use"
        termsOfUseAgree = "yes"
        publishing.onlyIf { true }
    }
}

Test reporting

The Gradle runner automatically parses JUnit and TestNG XML reports produced by Gradle’s test task. Test results appear on the Tests tab of the build results, including individual test durations, failure details, and history across builds.

No additional configuration is needed — TeamCity discovers TEST-*.xml files under build/test-results/ by default.

Build triggers and branch monitoring

Common trigger configurations for Gradle projects:

Trigger Usage

VCS Trigger

Polls the repository (default: every 60 seconds) and starts a build when changes are detected. Add +:refs/heads/* to the branch specification to monitor all branches.

Schedule Trigger

Runs builds on a cron schedule, e.g. nightly integration tests.

Pull Request builds

Enable the Pull Requests build feature and select your VCS provider (GitHub, GitLab, Bitbucket). TeamCity detects open pull requests and triggers builds automatically.

Commit Status Publisher

Reports build results back to the VCS provider, displaying pass/fail status on pull requests and commits.