MVP Factory
EN
ai startup development

Gradle Configuration Cache: Cut CI Build Times in Half

KW
Krystian Wiewiór · · 5 min read

Meta description: Deep dive into Gradle’s configuration cache internals — task graph serialization, cache miss root causes, incompatible plugins, and a step-by-step migration strategy for Android and KMP projects.

Tags: kotlin android kmp cicd multiplatform


TL;DR

Gradle’s configuration cache serializes the entire task graph to disk, skipping the configuration phase on subsequent builds. In multi-module Android and KMP projects, this can cut CI build times by 40–60%. Most teams stall on migration because they don’t understand why cache misses happen. The rest of this post covers that: the mental model and a systematic workflow for fixing them.


What the configuration cache actually does

The configuration cache is not a build cache. The build cache stores task outputs. The configuration cache stores the task graph — the DAG of tasks, their inputs, and their wiring — so Gradle can skip the configuration phase entirely on subsequent invocations.

The Gradle build lifecycle has three phases:

  1. Initialization — which projects participate
  2. Configuration — evaluate build.gradle.kts, construct the task graph
  3. Execution — run tasks

Configuration is expensive. In a 50-module Android project, evaluating every build.gradle.kts can consume 15–30 seconds on every CI run. The configuration cache eliminates this by serializing the resolved task graph to .gradle/configuration-cache/ as a binary snapshot and replaying it when inputs haven’t changed.


Why cache misses happen: the three root causes

1. Undeclared inputs

If your build script reads an environment variable or system property without declaring it as an input, Gradle can’t track it. Any change invalidates the entire cache.

// BAD — undeclared input, causes cache miss on every CI run
val version = System.getenv("BUILD_NUMBER")

// GOOD — declared as a provider, properly tracked
val version = providers.environmentVariable("BUILD_NUMBER")

2. File system reads at configuration time

Reading files during configuration (not execution) is a classic footgun. Gradle cannot fingerprint what it doesn’t know about.

// BAD — reads file at configuration time
val props = File("local.properties").readText()

// GOOD — deferred to execution via ValueSource
abstract class LocalPropertiesSource : ValueSource<String, ValueSourceParameters.None> {
    override fun obtain(): String = File("local.properties").readText()
}
val props = providers.of(LocalPropertiesSource::class) {}

3. Incompatible plugins

This is where most migrations stall. Third-party plugins that use Project references at execution time, mutate shared state, or use deprecated APIs will fail cache compatibility checks.

Plugin categoryTypical compatibilityCommon fix
AGP (8.x+)FullUpgrade to 8.x
KGP (1.9+)FullUpgrade to 1.9+
Custom in-house pluginsVariableRefactor to use Provider APIs
Legacy annotation processorsOften incompatibleMigrate to KSP
Some publishing pluginsPartialPin version, file issue upstream

The migration workflow

The most reliable path is incremental — never attempt a big-bang migration. I’ve watched teams flip the flag project-wide and spend weeks untangling the fallout.

Phase 1: establish a baseline with --warn

./gradlew assembleDebug --configuration-cache --configuration-cache-problems=warn

This runs with the cache enabled but treats problems as warnings, not failures. You’ll get an HTML report at build/reports/configuration-cache/. Open it. Every problem has a stack trace pointing to the exact line.

Phase 2: fix by category

Work through problems in this order: your code first, then plugins. Problems in your build scripts are cheap to fix. Waiting on upstream plugin fixes can take months.

// Replace direct Task references with lazy providers
// BAD
tasks.named("generateBuildConfig").get().outputs.files

// GOOD
tasks.named("generateBuildConfig").flatMap { it.outputs.files.elements }

Phase 3: fingerprinting debug for persistent misses

If the cache keeps missing after fixes, use verbose fingerprinting:

./gradlew assembleDebug --configuration-cache \
  -Dorg.gradle.configuration-cache.internal.report-file-system-access=true

This surfaces every file access during configuration, giving you a precise list of violations the standard report missed.

Phase 4: lock it in CI

# .github/workflows/build.yml
- name: Build
  run: ./gradlew assembleDebug --configuration-cache
  env:
    GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true

Treat any configuration cache failure as a build failure. This prevents regressions from slipping in.


Build time improvements

These numbers come from profiling real multi-module Android projects — treat them as rough benchmarks, not guarantees:

Project sizeConfig phase (before)Config phase (after)Total CI improvement
20 modules~12s~1s~18%
50 modules~28s~2s~35%
100+ modules~60s+~3s~50%+

Gains compound when you combine this with the build cache and remote cache (Develocity or GitHub Actions cache). The configuration cache eliminates the fixed cost per run; the build cache eliminates the incremental cost.


Where to start

  1. Run --configuration-cache-problems=warn today. You get the HTML report without breaking your build. Spend one sprint triaging the output before touching any code.

  2. Migrate your internal plugins first. Replace Project references with Provider-based APIs. This unblocks the majority of cache misses without waiting on external dependencies.

  3. Enforce it in CI as a hard failure. Once you’ve cleared the initial migration, any cache-incompatible code should fail the build. Discipline now saves you from months of drift later.


Share: Twitter LinkedIn