Record the current build before changing it
Save the AGP version, wrapper distribution, JVM used by Gradle, Android Studio version, compile SDK and important build plugins. Confirm that the current release builds and tests pass so regressions have a baseline.
The AGP release notes identify compatibility and migration changes. Consult the release you intend to adopt, not only a generic “latest version” page.
Plan the compatibility tuple
| Component | Where to verify |
|---|---|
| AGP | Plugin declaration or version catalog |
| Gradle | gradle-wrapper.properties and ./gradlew --version |
| Build JVM | IDE Gradle JDK and CI Java setup |
| Kotlin and processors | Their documented compatibility and plugin requirements |
| SDK/NDK | Installed versions required by the selected build |
Do not confuse the Java source language level with the JVM running Gradle. The Android JDK guide explains these separate roles.
Upgrade in a reviewable branch
Update the selected plugin and compatible wrapper, then address documented DSL or behavior migrations. Keep unrelated dependency upgrades out of the same change where possible. A smaller diff makes a new release-only crash or packaging change easier to attribute.
Use the wrapper update procedure and commit all required wrapper changes, not only a modified URL.
Validate more than sync
Run the release build, local tests, instrumentation tests where available, lint and any native or dynamic-feature builds. Inspect signing, manifest values, resource shrinking and output sizes. A successful IDE sync only proves the model imported; it does not prove the release behavior is unchanged.
Keep a rollback path
Retain the prior toolchain and release artifact until the new build is validated. APKLint's Build Analyzer can highlight configuration issues, and its APK tools can compare the resulting package. Neither can guarantee compatibility with every private plugin or compile your project from a short configuration excerpt.
Compare two artifacts from the same application
Build a baseline release from the current committed toolchain and retain its manifest, signing certificate identity, dependency report and output digest. Then apply the planned plugin and compatible wrapper change in a branch. Keep the application source and unrelated library versions stable where possible. This gives a practical before-and-after pair for investigating changes in packaging or shrinking.
Use the Android plugin release notes for the exact target version, including migration notes for the versions crossed. If Android Studio's upgrade assistant proposes edits, inspect each one and retain the reason. Automated edits can update syntax, but they cannot establish that a private convention plugin or custom packaging task still expresses the intended application behavior.
Investigate a release-only regression by stage
If debug builds work and the release fails, locate the first failing stage: source generation, compilation, resource processing, shrinking, native linking, signing or packaging. Capture the affected task and diagnostic rather than disabling release optimizations globally. For a shrinking regression, retain the mapping and a reproducible feature path. For a packaging change, inspect the actual entries and device configuration that receives them.
Exercise startup and the features that use reflection, serialization, JNI or dynamically delivered components when those mechanisms are present. A successful installation can miss an error reached only after authentication or loading a secondary feature. Use test accounts and synthetic data so the comparison does not depend on production credentials.
Check build reproducibility from a clean CI worker after the local migration succeeds. Record the effective JDK and installed SDK or NDK versions, because an unrecorded local tool can make the upgraded build appear healthier than the shared environment. Compare expected artifact properties rather than requiring identical APK bytes across a deliberate toolchain change; timestamps, metadata and compiler output may legitimately differ. Promote the candidate only with explained differences and passing relevant behavior checks. Keep the prior committed toolchain as a coherent rollback point until the release process accepts the new combination.
Sources and further reading
- Android Developers: Current Android Gradle plugin release notes
- Gradle: Gradle Wrapper
- Android Developers: Java versions in Android builds
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
