Cache Maven and Gradle wrapper distributions separately from the dependency cache

[brunoborges]

Description:

Each build tool's wrapper distribution was cached in the same cache entry as its dependency cache, keyed on volatile dependency files. Because those files change frequently and no restoreKeys are used (by design, see #269), almost every change rotates the key and produces a full cache miss. On a miss nothing is restored, including the rarely-changing wrapper distribution, so ./mvnw / ./gradlew re-download the build tool, which intermittently fails due to upstream rate limiting.

Maven: The wrapper distribution (~/.m2/wrapper/dists) shared the ~/.m2/repository entry, keyed on **/pom.xml (plus wrapper properties and extensions). I confirmed the impact from the linked JRuby run: the setup-java step logged maven cache is not found, then ./mvnw failed with wget: Failed to fetch https://repo1.maven.org/.../apache-maven-3.9.14-bin.zip. JRuby's maven-wrapper.properties changed only twice in about two years, while the repo has 31 pom.xml files that each rotate the shared key, so the wrapper was evicted far more often than it actually changes.

Gradle: The wrapper distribution (~/.gradle/wrapper) shared the ~/.gradle/caches entry, keyed on volatile files such as **/*.gradle*, with the same net effect — the wrapper was re-downloaded on nearly every dependency change.

Approach:

Give each build-tool wrapper distribution its own cache entry, keyed only on its wrapper properties file, so it survives the frequent dependency changes that invalidate the main dependency cache.

• Adds a generic additionalCaches concept to PackageManager, restored and saved independently with name-scoped state keys so restore/save state does not collide with the main cache.
• Moves ~/.m2/wrapper/dists out of the main maven path into a maven-wrapper additional cache keyed on **/.mvn/wrapper/maven-wrapper.properties.
• Moves ~/.gradle/wrapper out of the main gradle path into a gradle-wrapper additional cache keyed on **/gradle-wrapper.properties.
• Each additional cache is skipped silently when the project does not use the corresponding wrapper (no wrapper properties file).
• Keeps the cache-hit and cache-primary-key outputs driven by the main dependency cache, so existing behavior and outputs are unchanged.

Related issue:

Fixes: #1095

Check list:

• Ran npm run check locally (format, lint, build, test) and all checks pass.
• Mark if documentation changes are required.
• Mark if tests were added or updated to cover the changes.

[Copilot]

Pull request overview

This PR improves cache: maven reliability by splitting the Maven Wrapper distribution (~/.m2/wrapper/dists) into its own independently-keyed cache entry, so wrapper downloads are not evicted by frequent pom.xml-driven key rotations in the main Maven dependency cache.

Changes:

• Introduces a generic additionalCaches mechanism in the caching layer to restore/save auxiliary caches independently from the main dependency cache.
• Moves Maven Wrapper distributions to a separate cache entry keyed only on **/.mvn/wrapper/maven-wrapper.properties.
• Updates documentation and unit tests to reflect and validate the new caching behavior.

Show a summary per file

File	Description
src/cache.ts	Adds additionalCaches support and splits Maven wrapper dists into a separately-keyed cache entry.
tests/cache.test.ts	Updates/extends cache tests for Maven and adds coverage for wrapper cache restore/save behavior.
README.md	Documents that the Maven wrapper distribution cache is stored separately from the main Maven cache.
docs/advanced-usage.md	Updates advanced caching docs to describe the new separate wrapper cache entry and its rationale.
dist/setup/index.js	Updates the built distribution output to include the new caching logic.
dist/cleanup/index.js	Updates the built distribution output to include the new caching logic.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (1)

src/cache.ts:145

• The cache-key format described here doesn’t match the actual key produced by buildCacheKey (it includes the setup-java prefix, RUNNER_OS, and process.arch). This makes the documentation misleading for users/debugging.

/**
 * A function that generates a cache key to use.
 * Format of the generated key will be "${{ platform }}-${{ id }}-${{ fileHash }}"".
 * @see {@link https://docs.github.com/en/actions/guides/caching-dependencies-to-speed-up-workflows#matching-a-cache-key|spec of cache key}
 */

• Files reviewed: 4/6 changed files
• Comments generated: 3
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 4/6 changed files
• Comments generated: 3
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 4/6 changed files
• Comments generated: 0 new
• Review effort level: Low

[brunoborges]

Backport PR #1122