skip to content

How do you configure a remote HTTP build cache in Gradle, and where does that configuration live?

level: juniorimportance: must knowfreq 55%

answer

  1. settings.gradle.kts, not build.gradle
  2. remote<HttpBuildCache> { url = uri(...) }
  3. trailing slash on url
  4. org.gradle.caching=true to enable
  5. push defaults to false (read-only)

basics

~10 s

In settings.gradle(.kts) inside a buildCache block, declare remote(HttpBuildCache) and set its url to your cache server endpoint. It must also be enabled, typically with --build-cache or org.gradle.caching=true.

solid answer

~30 s

The remote HTTP cache is declared in the **settings file** (`settings.gradle.kts`), not `build.gradle.kts`, because the cache is configured for the whole build before projects load. Inside `buildCache { }` you call `remote<HttpBuildCache> { url = uri("https://cache.example.com/cache/") }`. The URL must end in a trailing slash; Gradle GETs entries by appending the cache key and PUTs to store. Configuring it does nothing unless the build cache itself is turned on (`org.gradle.caching=true` in `gradle.properties` or `--build-cache`). By default a remote cache is read-only (`push = false`) for safety, so most setups read from it locally and only enable push on trusted CI.

code

kotlin · 7 lines
kotlin
// settings.gradle.kts
buildCache {
    remote<HttpBuildCache> {
        url = uri("https://cache.example.com/cache/")
        // push defaults to false: read-only consumer
    }
}

go deeper

for a junior

Know the block goes in settings.gradle.kts and you set url; mention you must also enable caching.

for a middle

Explain configure-vs-enable distinction, trailing slash, and that push defaults to false.

for a senior

Discuss HTTPS, why settings-phase config, and the consumer-by-default / CI-pushes pattern.

for a principal

Frame org-wide rollout: standardize the settings config via a convention/init script and govern endpoints centrally.

## What the remote HTTP build cache is Gradle's **build cache** stores task outputs keyed by a hash of all the task's inputs. A *remote* cache shares those outputs across machines: if CI built a given input combination once, your laptop can download the result instead of recomputing it. The **HttpBuildCache** is the built-in remote backend that speaks plain HTTP to any compatible cache server (Gradle Enterprise / Develocity, or a simple Maven-repo-like server such as the `gradle/build-cache-node` Docker image). ## Where it is configured Build cache configuration lives in the **settings file** (`settings.gradle.kts`), inside a `buildCache { }` block. It belongs there — not in a project `build.gradle.kts` — because the cache must be wired up during the *settings* phase, before any project is evaluated. ```kotlin // settings.gradle.kts buildCache { remote<HttpBuildCache> { url = uri("https://cache.example.com/cache/") } } ``` Key points about the `url`: - It must end with a **trailing slash**. Gradle forms each entry URL by appending the cache key (a hex hash). A GET retrieves an entry; a PUT stores one. - Use **HTTPS** in any real deployment so credentials and artifacts are not sent in clear text. ## Enabling vs. configuring Declaring the remote cache does **nothing on its own**. The build cache feature is a separate switch: - `org.gradle.caching=true` in `gradle.properties`, or - `--build-cache` on the command line. With caching enabled and a remote configured, cacheable tasks consult the cache before executing. ## Push vs. pull By default the remote cache is **read-only**: `push = false`. That means the build will *download* hits but not *upload* new entries. This is intentional — you generally want only a trusted environment (CI) populating the shared cache, while developers consume it. To allow uploading you set `push = true` (covered in depth by the push/credentials material).

  • Why is build cache configured in the settings file rather than a build script?
    Because the cache is a build-wide service that must be available during the settings phase, before any project build script is evaluated; per-project configuration would be too late and inconsistent.
  • If you add the remote block but builds still recompute everything, what did you forget?
    Enabling the cache itself — set org.gradle.caching=true or pass --build-cache. The remote block only configures the backend; it doesn't switch caching on.

saying these in an interview costs you the question

  • Putting buildCache {} in build.gradle.kts instead of settings.gradle.kts.
  • Assuming declaring the remote cache enables caching by itself.
  • Omitting the trailing slash on the URL.

context

resolving links…