Skip to content

Backport #1097/#1098 to v5: cache Maven and Gradle wrapper distributions separately #1122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brunoborges merged 1 commit into from
Jul 14, 2026
Merged

Backport #1097/#1098 to v5: cache Maven and Gradle wrapper distributions separately #1122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ The workflow output `cache-primary-key` exposes the primary cache key computed b

The cache input is optional, and caching is turned off by default.

**Maven Wrapper:** when `cache: 'maven'` is enabled, the action also caches and restores the Maven Wrapper distribution downloaded to `~/.m2/wrapper/dists` (in addition to the local repository), so wrapper-based (`./mvnw`) builds don't re-download the wrapper on every run. This is keyed on `**/.mvn/wrapper/maven-wrapper.properties` as shown above.
**Maven Wrapper:** when `cache: 'maven'` is enabled, the action also caches and restores the Maven Wrapper distribution downloaded to `~/.m2/wrapper/dists` (in addition to the local repository), so wrapper-based (`./mvnw`) builds don't re-download the Maven distribution. The wrapper distribution is stored in a **separate** cache entry keyed only on `**/.mvn/wrapper/maven-wrapper.properties`, so it stays cached across the frequent `pom.xml` changes that rotate the main dependency cache key.

#### Caching gradle dependencies
```yaml
Expand All @@ -167,6 +167,8 @@ steps:
```
Using the `cache: gradle` provides a simple and effective way to cache Gradle dependencies with minimal configuration.

**Gradle Wrapper:** when `cache: 'gradle'` is enabled, the action also caches and restores the Gradle Wrapper distribution downloaded to `~/.gradle/wrapper` (in addition to the Gradle caches), so wrapper-based (`./gradlew`) builds don't re-download the Gradle distribution. The wrapper distribution is stored in a **separate** cache entry keyed only on `**/gradle-wrapper.properties`, so it stays cached across the frequent `*.gradle*` changes that rotate the main dependency cache key.

For projects that require more advanced `Gradle` caching features, such as caching build outputs, support for Gradle configuration cache, encrypted cache storage, fine-grained cache control (including options to enable or disable the cache, set it to read-only or write-only, perform automated cleanup, and define custom cache rules), or optimized performance for complex CI workflows, consider using [`gradle/actions/setup-gradle`](https://github.com/gradle/actions/tree/main/setup-gradle).

For setup details and a comprehensive overview of all available features, visit the [setup-gradle documentation](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md).
Expand Down
149 changes: 137 additions & 12 deletions __tests__/cache.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,10 +113,7 @@ describe('dependency cache', () => {

await restore('maven', '');
expect(spyCacheRestore).toHaveBeenCalledWith(
[
join(os.homedir(), '.m2', 'repository'),
join(os.homedir(), '.m2', 'wrapper', 'dists')
],
[join(os.homedir(), '.m2', 'repository')],
expect.any(String)
);
expect(spyGlobHashFiles).toHaveBeenCalledWith(
Expand All @@ -143,10 +140,7 @@ describe('dependency cache', () => {

await restore('maven', '');
expect(spyCacheRestore).toHaveBeenCalledWith(
[
join(os.homedir(), '.m2', 'repository'),
join(os.homedir(), '.m2', 'wrapper', 'dists')
],
[join(os.homedir(), '.m2', 'repository')],
expect.any(String)
);
expect(spyGlobHashFiles).toHaveBeenCalledWith(
Expand All @@ -161,10 +155,7 @@ describe('dependency cache', () => {

await restore('maven', '');
expect(spyCacheRestore).toHaveBeenCalledWith(
[
join(os.homedir(), '.m2', 'repository'),
join(os.homedir(), '.m2', 'wrapper', 'dists')
],
[join(os.homedir(), '.m2', 'repository')],
expect.any(String)
);
expect(spyGlobHashFiles).toHaveBeenCalledWith(
Expand All @@ -173,6 +164,39 @@ describe('dependency cache', () => {
expect(spyWarning).not.toHaveBeenCalled();
expect(spyInfo).toHaveBeenCalledWith('maven cache is not found');
});
it('restores the maven wrapper distribution cache independently of the main cache', async () => {
createFile(join(workspace, 'pom.xml'));
createDirectory(join(workspace, '.mvn'));
createDirectory(join(workspace, '.mvn', 'wrapper'));
createFile(
join(workspace, '.mvn', 'wrapper', 'maven-wrapper.properties')
);

await restore('maven', '');
// Main cache no longer includes the wrapper distribution.
expect(spyCacheRestore).toHaveBeenCalledWith(
[join(os.homedir(), '.m2', 'repository')],
expect.any(String)
);
// Wrapper distribution is restored on its own, keyed only on the
// maven-wrapper.properties hash.
expect(spyCacheRestore).toHaveBeenCalledWith(
[join(os.homedir(), '.m2', 'wrapper', 'dists')],
expect.any(String)
);
expect(spyGlobHashFiles).toHaveBeenCalledWith(
'**/.mvn/wrapper/maven-wrapper.properties'
);
});
it('skips the maven wrapper cache when no maven-wrapper.properties exists', async () => {
createFile(join(workspace, 'pom.xml'));

await restore('maven', '');
expect(spyCacheRestore).not.toHaveBeenCalledWith(
[join(os.homedir(), '.m2', 'wrapper', 'dists')],
expect.any(String)
);
});
});
describe('for gradle', () => {
it('throws error if no build.gradle found', async () => {
Expand Down Expand Up @@ -228,6 +252,30 @@ describe('dependency cache', () => {
expect(spyWarning).not.toHaveBeenCalled();
expect(spyInfo).toHaveBeenCalledWith('gradle cache is not found');
});
it('restores the gradle wrapper distribution cache independently of the main cache', async () => {
createFile(join(workspace, 'build.gradle'));
createDirectory(join(workspace, 'gradle'));
createDirectory(join(workspace, 'gradle', 'wrapper'));
createFile(
join(workspace, 'gradle', 'wrapper', 'gradle-wrapper.properties')
);

await restore('gradle', '');
// Main cache no longer includes the wrapper distribution.
expect(spyCacheRestore).toHaveBeenCalledWith(
[join(os.homedir(), '.gradle', 'caches')],
expect.any(String)
);
// Wrapper distribution is restored on its own, keyed only on the
// gradle-wrapper.properties hash.
expect(spyCacheRestore).toHaveBeenCalledWith(
[join(os.homedir(), '.gradle', 'wrapper')],
expect.any(String)
);
expect(spyGlobHashFiles).toHaveBeenCalledWith(
'**/gradle-wrapper.properties'
);
});
});
describe('for sbt', () => {
it('throws error if no build.sbt found', async () => {
Expand Down Expand Up @@ -399,6 +447,40 @@ describe('dependency cache', () => {
expect.stringMatching(/^Cache saved with the key:.*/)
);
});
it('saves the maven wrapper distribution cache under its own key', async () => {
createFile(join(workspace, 'pom.xml'));
createStateForWrapperRestore('maven-wrapper', false);

await save('maven');
expect(spyCacheSave).toHaveBeenCalledWith(
[join(os.homedir(), '.m2', 'wrapper', 'dists')],
'setup-java-maven-wrapper-primary-key'
);
});
it('does not save the maven wrapper cache on an exact wrapper hit', async () => {
createFile(join(workspace, 'pom.xml'));
createStateForWrapperRestore('maven-wrapper', true);

await save('maven');
expect(spyCacheSave).not.toHaveBeenCalledWith(
[join(os.homedir(), '.m2', 'wrapper', 'dists')],
expect.any(String)
);
});
it('does not fail the post step when the wrapper distribution path is missing', async () => {
createFile(join(workspace, 'pom.xml'));
createStateForWrapperRestore('maven-wrapper', false);
spyCacheSave.mockImplementation((paths: string[], key: string) => {
if (paths.includes(join(os.homedir(), '.m2', 'wrapper', 'dists'))) {
return Promise.reject(
new cache.ValidationError('Path Validation Error')
);
}
return Promise.resolve(0);
});

await expect(save('maven')).resolves.not.toThrow();
});
});
describe('for gradle', () => {
it('uploads cache even if no build.gradle found', async () => {
Expand Down Expand Up @@ -451,6 +533,26 @@ describe('dependency cache', () => {
expect.stringMatching(/^Cache saved with the key:.*/)
);
});
it('saves the gradle wrapper distribution cache under its own key', async () => {
createFile(join(workspace, 'build.gradle'));
createStateForWrapperRestore('gradle-wrapper', false);

await save('gradle');
expect(spyCacheSave).toHaveBeenCalledWith(
[join(os.homedir(), '.gradle', 'wrapper')],
'setup-java-gradle-wrapper-primary-key'
);
});
it('does not save the gradle wrapper cache on an exact wrapper hit', async () => {
createFile(join(workspace, 'build.gradle'));
createStateForWrapperRestore('gradle-wrapper', true);

await save('gradle');
expect(spyCacheSave).not.toHaveBeenCalledWith(
[join(os.homedir(), '.gradle', 'wrapper')],
expect.any(String)
);
});
});
describe('for sbt', () => {
it('uploads cache even if no build.sbt found', async () => {
Expand Down Expand Up @@ -528,6 +630,29 @@ function createStateForSuccessfulRestore() {
});
}

/**
* Create states to emulate a restore process where an additional (wrapper)
* cache was restored. When `hit` is true the matched key equals the primary
* key, emulating an exact wrapper cache hit.
*/
function createStateForWrapperRestore(wrapperName: string, hit: boolean) {
const primaryKey = `setup-java-${wrapperName}-primary-key`;
jest.spyOn(core, 'getState').mockImplementation(name => {
switch (name) {
case 'cache-primary-key':
return 'setup-java-cache-primary-key';
case 'cache-matched-key':
return 'setup-java-cache-matched-key';
case `cache-primary-key-${wrapperName}`:
return primaryKey;
case `cache-matched-key-${wrapperName}`:
return hit ? primaryKey : '';
default:
return '';
}
});
}

function createFile(path: string) {
core.info(`created a file at ${path}`);
fs.writeFileSync(path, '');
Expand Down
Loading
Loading