Gradle remote build cache setup

Declare the remote cache in settings.gradle.kts (Kotlin DSL) or settings.gradle (Groovy DSL), using your workspace token as the HTTP Basic password. The username is ignored - leave it empty:

// settings.gradle.kts (Kotlin DSL)
buildCache {
    remote<HttpBuildCache> {
        url = uri("https://remote.cachely.dev")
        isPush = System.getenv("CI") != null
        credentials {
            username = "" // unused; the token identifies you
            password = System.getenv("GRADLE_CACHE_TOKEN") // your Cachely token
        }
    }
}

// settings.gradle (Groovy DSL)
buildCache {
    remote(HttpBuildCache) {
        url = 'https://remote.cachely.dev'
        push = System.getenv('CI') != null
        credentials {
            username = '' // unused; the token identifies you
            password = System.getenv('GRADLE_CACHE_TOKEN') // your Cachely token
        }
    }
}

Enable the build cache for every invocation in gradle.properties (or pass --build-cache per run):

# gradle.properties
org.gradle.caching=true

Then export the token before building - locally from your shell, in CI from your secret store:

export GRADLE_CACHE_TOKEN=<your-token>
gradle build

Verify with gradle build --info and look for tasks reported as FROM-CACHE.

The isPush / push flag above is deliberately conditional on CI. Gradle's own recommendation is that continuous integration populates the cache from clean builds while developers only read from it: a developer machine has looser hermeticity guarantees, so an entry it publishes is the one most likely to be wrong. Pair that with a read-only token for pull requests and the boundary is enforced by Cachely rather than by convention - see tokens and access control.

The Gradle remote build cache guide covers how task output caching works and what makes a task cacheable. If stores are silently skipped, see troubleshooting.