Inspect the version that actually runs
./gradlew --version
Compare the output with gradle/wrapper/gradle-wrapper.properties. If they appear inconsistent, check which repository and wrapper script the shell or CI job invoked. Nested Android projects can have their own wrapper.
Select a compatible target
Read the selected AGP compatibility table before choosing a Gradle version. “Newest Gradle” is not automatically the right distribution for an older Android plugin or third-party build plugin.
The wrapper documentation describes the supported upgrade procedure, distribution types and verification options.
Update the wrapper as a set
A typical update command uses an explicit reviewed version:
./gradlew wrapper --gradle-version <compatible-version>
Replace the placeholder before execution. Follow the current wrapper guidance to refresh all required wrapper files and commit the relevant scripts, JAR and properties. Do not change only the URL and assume every wrapper component has been updated.
Verify download integrity and CI behavior
Use the publisher's documented distribution checksum where supported. Review changes to the wrapper JAR and scripts as executable build infrastructure, not as harmless metadata.
| Check | Evidence |
|---|---|
| Correct distribution | ./gradlew --version output |
| Correct JVM | Same output plus CI Java configuration |
| Reproducible invocation | CI calls the committed wrapper |
| Compatible build | Release and verification tasks succeed |
Keep rollback practical
Retain the previous committed wrapper and plugin combination until the new toolchain is validated. APKLint's Build Analyzer can review version declarations and errors, but it cannot verify a downloaded distribution or execute your private build. The decisive evidence is the committed wrapper and the actual local/CI output using it.
Trace the wrapper used by a nested Android build
In a framework repository, a CI job may start at the repository root but invoke the wrapper inside android/. Record the job's working directory and the exact script path. On Windows, the committed entry point is typically gradlew.bat; in a Unix-like shell it is ./gradlew. A globally installed gradle command can select a different distribution, even when both commands successfully configure the project.
Inspect the output from that exact wrapper invocation in CI. Compare its Gradle and JVM details with the developer environment, then check the committed distribution URL and checksum setting. The official wrapper guide distinguishes verification of the downloaded distribution from verification of the wrapper JAR. Both are executable parts of the build chain, but their checksums describe different files.
Review generated wrapper changes together
After selecting a compatible version, follow the documented wrapper task sequence to regenerate the required files. Review the scripts, JAR and properties as one change. If the wrapper task is first run using the old distribution, check whether the documented second invocation is needed to refresh the remaining components using the new distribution. A changed URL proves only which archive will be requested, not that every launcher component was regenerated.
Use a fresh authorized CI environment to confirm that the distribution can be downloaded and verified. A machine with an existing cached distribution might never exercise the download path, so its success would miss a wrong checksum or blocked URL. Keep approved proxy and repository configuration explicit, without embedding credentials in committed wrapper properties. Record a checksum-verification failure separately from a network timeout; retrying the latter does not justify accepting a different distribution digest.
Build the intended release and run the project's verification tasks after the wrapper check. If a third-party plugin fails, retain the compatibility evidence rather than immediately disabling its task. Roll back the wrapper and associated plugin changes together when they were selected as a tested pair. The release record should identify the complete toolchain combination and the tasks validated with it, making the upgrade reproducible for the next developer and the next clean CI worker.
Sources and further reading
Reference review: 29 September 2026. Examples illustrate the workflow; check your installed versions, release artifact and account-specific Console requirements before applying them. This guide is not a claim that APKLint executed your project or verified your private account.
Android inspection tools and practical release guides. About APKLint · Report a correction
