[build-tools] support Gradle build cache for Android builds by AbbanMustafa · Pull Request #3510 · expo/eas-cli

AbbanMustafa · 2026-03-17T01:34:44Z

Why

Android builds currently recompile all Kotlin/Java code from scratch on every build. We already persist ccache between builds to speed up native C/C++ compilation (NDK), but ccache doesn't help with the Gradle/Kotlin/Java layer — which is where the majority of Android build time is spent. This adds Gradle build cache support to close that gap, leading to more optimal Android builds.

How

All behavior is gated behind GRADLE_CACHE=1 — when unset, everything is a no-op.

Cache key is android-gradle-cache-{lockfile_hash}, derived from the project's package manager lockfile. Changing dependencies invalidates the cache; code-only changes reuse it. On miss, falls back to prefix match
(android-gradle-cache-) to find the closest available cache.

Two new build phases are added to the Android builder:

  RESTORE_CACHE              (ccache)
  RESTORE_GRADLE_CACHE       ← new
  POST_INSTALL_HOOK
  ...
  RUN_GRADLEW                (now with --build-cache flag)
  ...
  UPLOAD_APPLICATION_ARCHIVE
  SAVE_GRADLE_CACHE          ← new
  SAVE_CACHE                 (ccache)

Restore downloads and extracts the cache archive into ~/.gradle/caches/. Save compresses and uploads two specific subdirectories from ~/.gradle/caches/:

  ┌───────────────┬───────────────────────────────────────────────────────┬────────────────────┐
  │   Directory   │                       Contents                        │ Precompressed size │
  ├───────────────┼───────────────────────────────────────────────────────┼────────────────────┤
  │ build-cache-1 │ Gradle build cache — compiled classes, dex, resources │ ~130 MB            │
  ├────────────────────────────────────────────────────────────────────────────────────────────┤

We selectively cache build-cache-1 rather than the full ~/.gradle/caches/ directory. This subdirectory covers the highest-impact layers: compiled task outputs (classes, dex, resources). The remaining contents — transforms, journal, configuration-cache, etc. — are either derived from modules-2 (transforms are regenerated from cached dependencies on
first build) or are Gradle bookkeeping with negligible build time impact.

Test Plan

Validated locally, observed build time improvement of 4min -> 40sec

Ran Android build with GRADLE_CACHE=1 — first build misses, saves cache after completion
Ran second build — restores cache, skips save, ~130/386 Gradle tasks served FROM-CACHE
Ran across variants (assembleDebug, assembleRelease, bundleRelease) — all hit on the same cache
Ran without GRADLE_CACHE=1 — all cache phases no-op, no --build-cache flag passed

codecov · 2026-03-17T05:49:28Z

Codecov Report

❌ Patch coverage is 22.89157% with 64 lines in your changes missing coverage. Please review.
✅ Project coverage is 53.58%. Comparing base (99b8d67) to head (3d618df).
⚠️ Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
...ild-tools/src/steps/functions/restoreBuildCache.ts	15.79%	32 Missing ⚠️
.../build-tools/src/steps/functions/saveBuildCache.ts	17.86%	23 Missing ⚠️
packages/build-tools/src/utils/gradleCacheKey.ts	46.16%	7 Missing ⚠️
packages/build-tools/src/builders/android.ts	50.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3510      +/-   ##
==========================================
- Coverage   53.62%   53.58%   -0.03%     
==========================================
  Files         815      816       +1     
  Lines       34622    34752     +130     
  Branches     7192     7223      +31     
==========================================
+ Hits        18562    18618      +56     
- Misses      15979    16053      +74     
  Partials       81       81

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-03-17T06:52:07Z

Subscribed to pull request

File Patterns	Mentions
*/	@douglowder

Generated by CodeMention

sjchmiela · 2026-03-17T07:39:57Z

packages/build-tools/src/steps/functions/restoreGradleCache.ts

+
+const GRADLE_CACHES_DIR = '.gradle/caches';
+
+export function createRestoreGradleCacheFunction(): BuildFunction {


I don't see reason to add a new function? What is your reasoning re: having a single vs having multiple cache functions?

We talked before about introducing config like

cache: true cache: node_modules: true xcode: false gradle: false

or sth like that to the workflow YAML. If we had cache config in one object I don't think it makes sense to require user to set up different functions in custom jobs?

Shouldn't this be part of {restore,save}_build_cache?

I don't feel strongly about separate functions, can definitely fold this into {restore,save}_build_cache. I mainly wanted this PR to land the functionality so we can get feedback on how this works in prod, and then follow up with this and Xcode caches to set up introducing the proper config as a next step.

sjchmiela · 2026-03-17T07:43:20Z

packages/build-tools/src/android/gradle.ts

  logger.info(`Running 'gradlew ${gradleCommand}' in ${androidDir}`);
  await fs.chmod(path.join(androidDir, 'gradlew'), 0o755);
  const verboseFlag = ctx.env['EAS_VERBOSE'] === '1' ? '--info' : '';
+  const buildCacheFlag = ctx.env['GRADLE_CACHE'] === '1' ? '--build-cache' : '';


So sad Gradle can't be ordered to use build cache with an environment variable…

ah yes we can enable with gradle.properties

Oh I didn't mean gradle.properties would necessarily be better. I like the explicitness of --build-cache next to ./gradlew. Or maybe it would? Can we put gradle.properties anywhere, or only in the project?

eas-cli/packages/worker/src/external/analytics.ts

Line 144 in 25d945b

path.join(ctx.getReactNativeProjectDirectory(), 'android', 'gradle.properties'),

Would just appending \n... be sufficient?

yes we can do so via the project properties. I write to the file if we find the property has not been set daa3873#diff-db8c2375feedbfe1a1b25cbc4ef8375f0d592509438f4babcc5db95d6f28cdc1R57-R69

packages/build-tools/src/steps/functions/restoreGradleCache.ts

sjchmiela · 2026-03-17T07:47:38Z

packages/build-tools/src/steps/functions/saveGradleCache.ts

+import { generateGradleCacheKeyAsync } from '../../utils/gradleCacheKey';
+
+const GRADLE_CACHES_DIR = '.gradle/caches';
+const CACHE_SUBDIRS = ['build-cache-1', 'modules-2'];


I think we shouldn't cache modules-2. As you mentioned, those are Maven/Gradle artifacts and dependencies. To help with that we have the Maven cache proxy. If we start caching these for all builds we'll go from storing one artifact in the Maven cache for all the builds to use to storing one artifact for every build separately. This is going to inflate network bandwidth and cache size a lot.

Can you confirm if caching just the build-cache-1 helps too? https://docs.gradle.org/current/userguide/build_cache.html does not mention modules-2, it does however talk about build-cache.

I saw speed benefits when restoring modules-2, but in terms of the gradle's reported cache hit, it performs the same. So yes I was just observing locally the benefits of what our maven repo provides for the worker. So I will remove modules-2

sjchmiela · 2026-03-17T07:57:56Z

packages/build-tools/src/steps/functions/saveGradleCache.ts

+    const expoApiServerURL = nullthrows(env.__API_SERVER_URL, '__API_SERVER_URL is not set');
+
+    logger.info(`Compressing Gradle caches (${existingDirs.join(', ')})...`);
+    const { archivePath } = await compressCacheAsync({


What about configuring cache pruning?

https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home:configure_cache_cleanup

packages/build-tools/src/android/gradle.ts

AbbanMustafa · 2026-03-17T23:01:46Z

with EAS_GRADLE_CACHE: '1', consolidate caches in restore/save step

with no or EAS_GRADLE_CACHE: '0', no-op

sjchmiela · 2026-03-18T14:59:53Z

packages/build-tools/src/steps/functions/restoreBuildCache.ts

+  workingDirectory: string;
+  env: Record<string, string | undefined>;
+  secrets?: { robotAccessToken?: string };
+}): Promise<boolean> {


Suggested change

}): Promise<boolean> {

}): Promise<{ restored: boolean }> {

or cacheHit or sth like that?

sjchmiela · 2026-03-18T15:02:15Z

packages/build-tools/src/steps/functions/restoreBuildCache.ts

+  const properties = AndroidConfig.Properties.parsePropertiesFile(gradlePropertiesContent);
+
+  let modified = false;
+  if (!properties.some(p => p.type === 'property' && p.key === 'org.gradle.caching')) {
+    properties.push({ type: 'property', key: 'org.gradle.caching', value: 'true' });
+    modified = true;
+  }
+  if (!properties.some(p => p.type === 'property' && p.key === 'org.gradle.cache.cleanup')) {
+    properties.push({ type: 'property', key: 'org.gradle.cache.cleanup', value: 'ALWAYS' });
+    modified = true;
+  }
+  if (modified) {
+    await fs.promises.writeFile(
+      gradlePropertiesPath,
+      AndroidConfig.Properties.propertiesListToString(properties)
+    );
+  }


Should we allow custom properties for org.gradle.caching and org.gradle.cache.cleanup if a user uses EAS_GRADLE_CACHE? To put it differently, shouldn't EAS_GRADLE_CACHE override whatever the user has set?

Yes, I agree if the user opts in then that should set precedent for the properties. Can also tweak more how the customization looks once this our

sjchmiela · 2026-03-18T15:02:51Z

packages/build-tools/src/steps/functions/restoreBuildCache.ts

+    const cacheKey = await generateGradleCacheKeyAsync(workingDirectory);
+    logger.info(`Restoring Gradle cache key: ${cacheKey}`);
+
+    const jobId = nullthrows(env.EAS_BUILD_ID, 'EAS_BUILD_ID is not set');


Why do we do nullthrows sometimes inside try and sometimes outside try?

sjchmiela · 2026-03-18T15:03:59Z

packages/build-tools/src/steps/functions/restoreBuildCache.ts

+    });
+
+    await fs.promises.mkdir(gradleCachesPath, { recursive: true });
+    await spawn('tar', ['xzf', archivePath, '-C', gradleCachesPath], { logger });


Why can't we use the regular cache utilities?

sjchmiela · 2026-03-18T15:04:30Z

packages/build-tools/src/steps/functions/saveBuildCache.ts

+  }
+
+  if (cacheHit) {
+    logger.info('Gradle cache was restored — skipping save');


Why are we skipping save if restored?

sjchmiela · 2026-03-18T15:05:07Z

packages/build-tools/src/steps/functions/saveBuildCache.ts

+    return;
+  }
+
+  const existingDirs = [];


can we simplify?

sjchmiela · 2026-03-18T15:06:06Z

packages/build-tools/src/steps/functions/restoreBuildCache.ts

+      paths: ['gradle-caches'],
+      key: cacheKey,
+      keyPrefixes: [GRADLE_CACHE_KEY_PREFIX],


This does not match compressCacheAsync in saveBuildCache which means version won't match and cache will never get restored? Did you test this?

Its a bit confusing with the parameter naming, but paths in compressCacheAsync and paths in uploadCacheAsync/downloadCacheAsync are for different purpose. And we just need it consistent between the up/download functions. I believe you meant upload since that is what determines the version, which was the same https://github.com/expo/eas-cli/pull/3510/changes#diff-b282ed96909cf3405e277859d596a3617f65db34f4f22319efcd062a549a3430R207

I've aligned them all now to just have ['build-cache-1'] as path to be consistent with how ccache does it and avoid confusion.

github-actions · 2026-03-25T04:35:56Z

⏩ The changelog entry check has been skipped since the "no changelog" label is present.

AbbanMustafa · 2026-03-25T04:36:20Z

sjchmiela

Much, much nicer! Left a few questions

sjchmiela · 2026-03-25T09:05:28Z

packages/build-tools/src/steps/functions/restoreBuildCache.ts

+
+    const propsToSet: Record<string, string> = {
+      'org.gradle.caching': 'true',
+      'org.gradle.cache.cleanup': 'ALWAYS',


Looks like we'll need to either handle Gradle 9.0 in a dedicated way or move to init script as per https://docs.gradle.org/current/userguide/upgrading_major_version_9.html#removal_of_org_gradle_cache_cleanup. We want to support Gradle 9 https://exponent-internal.slack.com/archives/C1QP38NQ5/p1772688272258629

Also, I think the default expiration times are too high for us?

sjchmiela · 2026-03-25T09:06:34Z

packages/build-tools/src/steps/functions/restoreBuildCache.ts

+    const properties = AndroidConfig.Properties.parsePropertiesFile(gradlePropertiesContent);
+
+    const propsToSet: Record<string, string> = {
+      'org.gradle.caching': 'true',
+      'org.gradle.cache.cleanup': 'ALWAYS',
+    };
+
+    for (const [key, value] of Object.entries(propsToSet)) {
+      const existing = properties.find(p => p.type === 'property' && p.key === key);
+      if (existing && existing.type === 'property') {
+        existing.value = value;
+      } else {
+        properties.push({ type: 'property', key, value });
+      }
+    }
+
+    await fs.promises.writeFile(
+      gradlePropertiesPath,
+      AndroidConfig.Properties.propertiesListToString(properties)
+    );


Is this better than ⬇️ ? (sth like)

Suggested change

const properties = AndroidConfig.Properties.parsePropertiesFile(gradlePropertiesContent);

const propsToSet: Record<string, string> = {

'org.gradle.caching': 'true',

'org.gradle.cache.cleanup': 'ALWAYS',

};

for (const [key, value] of Object.entries(propsToSet)) {

const existing = properties.find(p => p.type === 'property' && p.key === key);

if (existing && existing.type === 'property') {

existing.value = value;

} else {

properties.push({ type: 'property', key, value });

}

}

await fs.promises.writeFile(

gradlePropertiesPath,

AndroidConfig.Properties.propertiesListToString(properties)

);

await fs.promises.writeFile(

gradlePropertiesPath,

`${gradlePropertiesContent}\n\norg.gradle.caching=true\norg.gradle.cache.cleanup=ALWAYS\n`

);

?

sjchmiela · 2026-03-25T09:07:17Z

packages/build-tools/src/steps/functions/restoreBuildCache.ts

+      jobId,
+      expoApiServerURL,
+      robotAccessToken,
+      paths: ['build-cache-1'],


Why not use path.join(gradleCachesPath, 'build-cache-1')?

AbbanMustafa added 2 commits March 16, 2026 20:34

gradle cache

17ab695

cache modules-2

2e61329

AbbanMustafa added the no changelog PR that doesn't require a changelog entry label Mar 17, 2026

cache modules-2

c67ed62

AbbanMustafa changed the title ~~gradle cache~~ [build-tools] support Gradle build cache for Android builds Mar 17, 2026

proper path

814daf3

AbbanMustafa marked this pull request as ready for review March 17, 2026 06:51

douglowder approved these changes Mar 17, 2026

View reviewed changes

AbbanMustafa requested a review from sjchmiela March 17, 2026 06:59

sjchmiela requested changes Mar 17, 2026

View reviewed changes

AbbanMustafa added 4 commits March 17, 2026 15:29

set properties, rename

5b8dc8d

rem modules-2

81f7420

set org.gradle.cache.cleanup to ALWAYS

daa3873

set org.gradle.cache.cleanup to ALWAYS

6e04df1

consolidate caches in restore/save step

7fcd310

AbbanMustafa requested a review from sjchmiela March 17, 2026 23:18

sjchmiela requested changes Mar 18, 2026

View reviewed changes

AbbanMustafa added 5 commits March 24, 2026 01:09

restore gradle

619e0d1

cleanup nullthrows

d064d03

always set properties if env set, cleanup

1b1e58a

consistent path, clean log

d47fd92

modify gradle props in trycatch

3d618df

AbbanMustafa requested a review from sjchmiela March 25, 2026 04:43

sjchmiela requested changes Mar 25, 2026

View reviewed changes


		const GRADLE_CACHES_DIR = '.gradle/caches';

		export function createRestoreGradleCacheFunction(): BuildFunction {

Conversation

AbbanMustafa commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

How

Test Plan

Uh oh!

codecov bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AbbanMustafa commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 25, 2026

Uh oh!

AbbanMustafa commented Mar 25, 2026

Uh oh!

sjchmiela left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AbbanMustafa commented Mar 17, 2026 •

edited

Loading

codecov bot commented Mar 17, 2026 •

edited

Loading

AbbanMustafa commented Mar 17, 2026 •

edited

Loading