Setting up Gradle Build Cache

The Gradle build cache is a cache mechanism that saves build time by reusing task outputs from previous builds. When Gradle determines that a task's inputs have not changed, it can fetch stored outputs from the cache instead of running the task again. Build outputs can be stored in a remote build cache and shared across machines.

With a remote HTTP build cache, Gradle can store and resolve task outputs across developer workstations, CI, and AI agent environments. In a typical setup, CI pipelines read from and write to the shared remote build cache in every build, while developers and AI agents read from the cache without pushing new entries (because CI environment is usually more reproducible). This task output caching model lets every machine benefit from work already done on other machines thus saving up to 90% CPU time and CI costs in bill-per-time environments such as GitHub Actions CI.

Instead of recompiling, retesting, and repackaging on every machine, Gradle loads cached results and reports tasks as FROM-CACHE — turning work that takes minutes into cache lookups that finish in seconds or even milliseconds.

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

First build (CI populates the remote cache — say ~10 minutes):

$ ./gradlew clean assemble --build-cache

> 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 (developer, AI agent, or fresh CI agent — ~4 seconds):

$ ./gradlew clean assemble --build-cache

> 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 CI environments where CI agents are recreated on every run, and in actively developed projects where CI continuously warms the shared cache for the whole team.

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

Gradle is extremely flexible in how build cache configuration is wired due to setup being written in programming language. BuildFetch's recommended simple approach is to configure settings.gradle.kts like so:

buildCache {
    remote<HttpBuildCache> {
        isEnabled = true

        url = uri("<remote cache url>")

        credentials {
            username = "token-auth"
            password = "<generated token>"
        }

        isPush = System.getenv("ON_CI") != null
    }
}

On CI, you can provide credentials 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="..."
export ON_CI="true"

./gradlew build --build-cache

Then read those values in settings.gradle.kts:

buildCache {
    remote<HttpBuildCache> {
        isEnabled = true

        url = uri(System.getenv("BUILDFETCH_GRADLE_REMOTE_CACHE_URL"))

        credentials {
            username = "token-auth"
            password = System.getenv("BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN")
        }

        isPush = System.getenv("ON_CI") != null
    }
}