Before a Gradle major upgrade, move to the latest release of your current line, run the build and clear every deprecation warning, then update plugins that use removed internal APIs. Change the wrapper version in its own pull request, and run the full build and tests.
What the upgrade guide recommends
Gradle's upgrade documentation for the 8.x line gives a preparation sequence. Run the build and review deprecation warnings that apply to it. It also mentions running the help task with a warning mode option set to all, to see deprecations in the console, with the caution that this may report less detail than the full build report. It then says to update your plugins, because some plugins break with a new Gradle version when they use internal APIs that have been removed or changed. The preceding step helps you spot those, since the warnings appear when a plugin touches a deprecated part of the API.
Steps
- Record the current wrapper version and the Java version your build runs on.
- Upgrade to the newest release of your current major first. Fix anything that appears.
- Run the build with the console warning mode.
./gradlew help --warning-mode=all
- Fix warnings in your own build scripts and convention plugins.
- List every plugin, with its version, and check for a release that supports the target Gradle.
- Update plugins first, while still on the old Gradle if they support both.
- Change the wrapper in a separate commit.
./gradlew wrapper --gradle-version <target>
- Run the full build, tests and any release tasks on a branch.
- Compare outputs: archive contents, dependency lists, test counts.
Where problems hide
| Area | What goes wrong |
|---|---|
| Community plugins | Use removed internals, need a newer release |
| Custom build logic | Relies on deprecated APIs in your buildSrc or convention plugins |
| Java toolchain | A newer Gradle may need a newer JVM to run |
| CI caches | Stale cache entries hide a failure until a clean run |
Run one clean build in CI with caches disabled to catch the last category.
Check dependencies before and after
A build tool upgrade can change how dependencies resolve, for example through different conflict handling or changed default configurations. Take a dependency listing before the upgrade and after, and diff them. Any difference should have an explanation. An unexpected version change is either a harmless resolution tweak or a surprise, and you want to know which.
If you produce an SBOM at release time, generate it from both builds and compare. That gives a record that the upgrade did not change what you ship, or exactly what it changed.
Keep it reversible
Keep the wrapper change small so that reverting means one commit. Do not combine it with dependency upgrades or Java version changes. If the build fails, you want exactly one variable to blame.
Quick check
Why update plugins before the Gradle version?
Plugins that use internal APIs can break on a new Gradle. Updating them first, where they support both versions, removes that variable.
Should I change Gradle and the JDK in one pull request?
No. Separate them so a failure points at one cause.
Safeguard produces SBOMs and scans Gradle dependencies, so you can compare what shipped before and after a build tool change. Try the free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
