Android Studio Gradle Wrapper Upgrade Prompt Persistence Limits

Why the Upgrade Prompt Reappears

Android Studio compares the Android Gradle Plugin (AGP) version you declare in build.gradle with the Gradle distribution URL in gradle/wrapper/gradle-wrapper.properties. If the two are out of the supported range, the IDE offers to run the wrapper update and records your accept or defer choice in .idea/workspace.xml. That file is user‑specific and normally excluded from VCS, so the decision never propagates to other developers or CI agents.

Can the Decision Be Stored in VCS?

No. The IDE has no mechanism to write the accept/defer flag to a version‑controlled file. The only durable source of truth is gradle-wrapper.properties itself. The wrapper script and JAR are regenerated by the wrapper Gradle task, and the distributionUrl (and optionally distributionSha256Sum) pin the exact Gradle release that will be downloaded.

Enforcing a Single Gradle Version

1. Pin the AGP version in a committed location (e.g., settings.gradle, a version catalog, or gradle/libs.versions.toml).
2. Pin the Gradle distribution in gradle/wrapper/gradle-wrapper.properties by running:

   ./gradlew wrapper --gradle-version <target> \\\n  --gradle-distribution-sha256-sum <sha256>

3. Commit the resulting changes: gradle/wrapper/gradle-wrapper.jar, gradle/wrapper/gradle-wrapper.properties, and the gradlew scripts.
4. Verify locally:

   ./gradlew --version

   The output must match the distributionUrl.
5. Add a CI check that fails if gradle-wrapper.properties or the wrapper JAR differ from the committed snapshot. Optionally validate the distributionSha256Sum to guard against supply‑chain tampering.

Can the Prompt Be Disabled?

There is no dedicated IDE setting to suppress only the wrapper‑upgrade suggestion while keeping other compatibility checks. The prompt is triggered by a detected mismatch, so the simplest way to avoid it is to keep the AGP and Gradle versions in a compatible pair per the AGP‑Gradle compatibility matrix. When the two match, the IDE will not offer the upgrade dialog.

Practical Steps for a Team

1. Decide on a stable AGP/Gradle pair (e.g., AGP 8.1.0 with Gradle 8.9).
2. Run the wrapper task once on a clean checkout:

   ./gradlew wrapper --gradle-version 8.9 \\\n  --gradle-distribution-sha256-sum 1234567890abcdef

3. Commit the wrapper artefacts and gradle-wrapper.properties.
4. Add a pre‑commit or CI hook that checks gradle-wrapper.properties for unexpected changes.
5. Optionally add a script that prints the expected distributionUrl and fails if the local wrapper differs.

Summary

Because the IDE’s accept/defer flag lives only in workspace.xml, you cannot persist it in VCS. The reliable way to enforce a consistent Gradle version is to pin the wrapper distribution in gradle-wrapper.properties, commit the wrapper artefacts, and add CI checks that guard against accidental drift. Keeping AGP and Gradle in a supported pair eliminates the prompt entirely.