docs: document seeding the Maven cache for plugin dependencies - #1094
Merged
brunoborges merged 5 commits intoJul 9, 2026
Merged
docs: document seeding the Maven cache for plugin dependencies#1094brunoborges merged 5 commits into
brunoborges merged 5 commits into
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
Explain that setup-java's maven cache only stores what a run downloads and is not re-saved on a hit, so plugin dependencies resolved lazily (e.g. by maven-shade-plugin) can be missing from the cache. Document a dependency resolution 'seed' step (dependency:go-offline + dependency:resolve-plugins) in README and a fuller advanced-usage section with a goal-comparison table, single-job and separate-seed-job examples, and caveats. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
#990) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…#705) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation update explaining a common limitation of cache: maven in actions/setup-java: Maven plugin dependencies are resolved lazily, so an initial cache created by a “thin” goal may not include plugin deps, causing repeated downloads on subsequent CI runs.
Changes:
- Added a brief note in the README under “Caching maven dependencies” pointing to an advanced guide section.
- Added a new advanced-usage section describing why plugin deps can be missing and how to seed a more complete Maven cache (with examples and caveats).
| File | Description |
|---|---|
| README.md | Adds a short note linking to the advanced guidance about seeding Maven plugin dependencies into the cache. |
| docs/advanced-usage.md | Adds a new section detailing the root cause and recommended seeding commands/workflow patterns to produce a more complete Maven cache. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 2/2 changed files
- Comments generated: 1
- Review effort level: Low
Sorry, something went wrong.
Comment thread
docs/advanced-usage.md
This was referenced Jul 9, 2026
brunoborges
added a commit
that referenced
this pull request
Jul 9, 2026
Address post-merge review feedback on #1094: the intro paragraph described the cache too narrowly. setup-java caches both ~/.m2/repository and ~/.m2/wrapper/dists, and the default key hashes **/pom.xml plus .mvn/wrapper/maven-wrapper.properties and .mvn/extensions.xml, so changing wrapper/extensions files also invalidates the cache. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description:
With cache: maven, the action stores whatever a run downloads into ~/.m2 and does not re-save on a cache hit. Because Maven resolves plugin dependencies lazily (only for the goals that actually execute), a cache first created by a "thin" goal such as mvn compile never captures plugins bound to later phases. For example maven-shade-plugin and its dependencies (plexus-archiver, commons-compress, aircompressor, xz) are missing, so every later test/verify/package job re-downloads them on each run. The same effect hits parallel matrix jobs that each run a partial goal and race to save an incomplete cache (issue #705). This behavior was reproduced and confirmed on the current main.
This is a documentation-only change. It explains the behavior and shows how to seed a complete cache; it does not change the action's caching code.
The recommended seed is mvn -B dependency:go-offline dependency:resolve-plugins, verified to produce a superset that lets a subsequent build download nothing.
The section is honest about limits: the seed only helps on the run that creates the cache (an already-incomplete cache must be invalidated once), static resolution is not exhaustive (profile/module/execution-time gaps), and multi-module builds should seed at the reactor root. A closing note flags that cache: gradle has the same limitation and points Gradle users to gradle/actions/setup-gradle for complete dependency caching.
Related issue:
Fixes: #990
Addresses: #705
Check list: