Configure Gradle Build Cache

The Gradle Build Cache saves significant amount of build time by reusing Gradle Task outputs from previous builds when a task's inputs have not changed. Gradle Build Cache can be both Local and Remote.

For each Cacheable Task, Gradle hashes declared inputs into a cache key, then looks up that key in the Gradle Build Cache. On a cache miss Gradle run the task (slow) and stores the outputs; on a cache hit Gradle restores outputs (fast) and skips the slow task run.

Schematic example: say a first run of :libs:dto:compileKotlin with a few dozen Kotlin source files misses the cache, spends ~15 seconds compiling, and stores the resulting jar output file under the computed key:

:libs:dto:compileKotlin

  Inputs
  +----------------------+
  | UserDto.kt           |
  | ...                  |
  | Mapper.kt            |
  +----------+-----------+
             |
             v
  Compute cache key from inputs
             |
             v
  +----------------------+
  | Gradle Build Cache   |
  | key: a3f9...c2       |
  | status: MISS         |
  +----------+-----------+
             |
             v
  Compile Kotlin (~15s)
             |
             v
  Output: dto.jar
             |
             v
  Store dto.jar under key a3f9...c2

Later builds with the same inputs reuse that entry. Gradle computes the same cache key, hits the Remote Gradle Build Cache, and restores dto.jar in say ~40ms instead of compiling for ~15 seconds — so that node in the build graph finishes almost immediately:

:libs:dto:compileKotlin  (same inputs)

  Inputs unchanged
  UserDto.kt · ... · Mapper.kt
             |
             v
  Same cache key: a3f9...c2
             |
             v
  +----------------------+
  | Gradle Build Cache   |
  | key: a3f9...c2       |
  | status: HIT          |
  +----------+-----------+
             |
             v
  Download dto.jar (~40ms)
             |
             v
  Skip ~15s compile
  Task reports FROM-CACHE
  Build graph continues sooner

A remote Gradle Build Cache lets teams share task outputs across engineer workstations, CI, and AI agent environments.

CI, having a more reproducible and controlled environment, typically both reads from and writes to the shared Gradle Build Cache. Engineers and AI agents read those outputs without uploading new entries.

That keeps the cache warm from reproducible CI builds while reducing repeated work on other machines.

Instead of recompiling, retesting, and repackaging on every machine, Gradle loads cached results and reports tasks as FROM-CACHE — turning builds that took minutes into cached builds that finish in seconds.

After CI populates the Gradle Build Cache, a clean build on another machine can resolve every expensive task from cache. In a typical scenario:

First build (CI populates the Gradle Build Cache — ~10 minutes):

$ ./gradlew clean assemble

> Task :compileJava
> Task :processResources
> Task :classes
> Task :compileTestJava
> Task :processTestResources
> Task :testClasses
> Task :test
> Task :jar
> Task :assemble

BUILD SUCCESSFUL in 10m 4s

Subsequent build (engineer, AI agent, or fresh CI agent — ~4 seconds):

$ ./gradlew clean assemble

> Task :compileJava FROM-CACHE
> Task :processResources FROM-CACHE
> Task :classes FROM-CACHE
> Task :compileTestJava FROM-CACHE
> Task :processTestResources FROM-CACHE
> Task :testClasses FROM-CACHE
> Task :test FROM-CACHE
> Task :jar FROM-CACHE
> Task :assemble FROM-CACHE

BUILD SUCCESSFUL in 4s

Remote Gradle Build Cache is especially valuable in ephemeral, autoscalable CI environments, where CI agents are often recreated run without the disk state.

It also tremendously helps in actively developed projects where CI continuously warms the shared cache for the whole team as codebase evolves with each commit.

Gradle Build Cache is disabled by default until you explicitly enable it..

We suggest enabling it for the whole Project with org.gradle.caching=true in gradle.properties and commit that file so CI, engineers, and AI agents all run with caching.

org.gradle.caching=true

Alternatively you can pass --build-cache flag in each individual Gradle invocation should you choose to do so. After caching is enabled, configure a remote Gradle Build Cache backend such as BuildFetch Cache (next section).

Official Gradle Build Cache documentation: https://docs.gradle.org/current/userguide/build_cache.html.

Gradle configuration is written in Kotlin or Groovy. Gradle Build Cache settings usually live in settings.gradle.kts.

Generate Tokens

We recommend generating a cache:readwrite Token for CI and cache:readonly Token(s) for engineer machines.

Generally, there are two ways to manage engineer Tokens:

• For simpler setups, issuing and rotating a single cache:readonly Token could be sufficient.
• For precise access control, each engineer should register in BuildFetch, then issue and rotate their own individual cache:readonly Token(s).

Generating cache:readwrite Tokens requires Project/Org Admin scope.

For Open Source Projects, we recommend not storing a cache:readonly Token in publicly accessible code because it could lead to misuse and unintended exhaustion of monthly Project limits.

For a simple Kotlin setup, add the remote Gradle Build Cache to settings.gradle.kts. Use the Project cache URL from the Project Cache Setup tab and pass the generated Token via environment variable (best for CI) or ~/.gradle/gradle.properties (best for a mixed IDE and terminal experience):

buildCache {
    remote<HttpBuildCache> {
        url = uri("<gradle build cache url>")

        credentials {
            username = "token-auth"

            // Set BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN="generated-token" as env variable (best for CI)
            // Set BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN="generated-token" in ~/.gradle/gradle.properties (best for mixed IDE & Terminal experience)
            password = "BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN".let {
                providers.environmentVariable(it).orElse(providers.gradleProperty(it)).orNull
            }
        }

        // BuildFetch recommends starting with Cache writes enabled on CI (more reproducible environment).
        // On engineer machines, enable writes if this environment is trusted & reproducible for quicker cache distribution and higher hit ratio.
        isPush = providers.environmentVariable("CI").isPresent

        isEnabled = url != null && credentials.username != null && credentials.password != null
    }
}

On CI, set the Token (and optionally the URL) through environment variables, for example:

export BUILDFETCH_GRADLE_REMOTE_CACHE_URL="https://cache.example.buildfetch.com/project-id/gradle/"
export BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN="..."

./gradlew build