Google Play Staged Rollout Explained: When to Use It
How to release an update to a percentage of users, how to halt or resume and a simple plan for safe rollouts.
Read the guide →How to Update an App on Google Play (New Version)
Quick answer To update an app on Google Play, raise the versionCode, build a new signed bundle with the same upload key, test it, upload it with release notes and roll it out, ideally as a staged rollout.
Publishing your first version is hard. Publishing the second is where many developers get tripped up by version codes, keys and forms they have forgotten. This guide shows how to update an app on Google Play as a repeatable routine: what to change in your project, how to upload and describe the release, which checks to run and how to roll out without putting every user at risk.
How do you update an app on Google Play?
- Change the codeFix bugs and add features on a release branch.
- Raise versionCode and versionNameversionCode must increase every release.
- Build a signed AABUse the same upload keystore. See how to create an AAB file.
- Test the bundleUpload to an internal track and install from Google Play.
- Create the production releaseUpload the bundle and write release notes.
- Check declarationsUpdate forms that the changes affect.
- Start a staged rolloutRelease to a small percentage first. See staged rollout explained.
- Watch and expandMonitor crashes and reviews, then increase the percentage.
How do versionCode and versionName work?
Google's versioning documentation defines two values in your module's build.gradle:
| Setting | Meaning | Rule |
|---|---|---|
| versionCode | Internal integer used to decide which version is newer. Users do not see it. | Must increase with each release. You cannot reuse a value. Maximum 2100000000. |
| versionName | The version text users see, for example 1.2.0 | Any string. It is the only version value displayed to users. |
defaultConfig {
versionCode = 12
versionName = "1.3.0"
}Keep a habit: if Play Console has ever seen a code, never use it again, even for a build you deleted. When in doubt, increase by more than one.
How do you build the new bundle?
Use Build > Generate Signed App Bundle / APK, or run ./gradlew bundleRelease with signing configured, exactly as in our AAB guide. Choose the same keystore. If you cannot find it, read how to reset an upload key before the release date, not after.
Why test before production?
| Track | Use it for | Notes |
|---|---|---|
| Internal testing | Quick check on a few devices | Fast to publish. See internal vs closed testing |
| Closed testing | Beta with real users | Your original 12-tester test remains a requirement history, not something to repeat for every update |
| Production staged rollout | Real release to a fraction of users | Increase gradually |
Open the internal build on a real phone and test installation, login, purchases, the main flow and any screen you changed. Test an update install on top of the previous version, not only a fresh install.
How do you upload and write release notes?
- Open the trackChoose Production (or a test track) in Play Console.
- Create a new releaseClick Create new release.
- Upload the new bundleDrag the .aab into the box.
- Write release notesSay what is new in a few friendly lines for each language you support.
- Review the summaryFix errors. Read warnings.
- Save and send for reviewThen roll out when ready.
Good release notes are short and honest: what is new, what is fixed, and nothing the update does not deliver. Claiming features that are not there can create review problems.
Which declarations do you need to re-check?
| If your update... | Check |
|---|---|
| Adds chat, ads, purchases or mature content | Content rating. See the questionnaire guide |
| Adds or changes data collection or SDKs | Data safety form and privacy policy. See the Data safety guide |
| Changes who the app is for | Target audience. See the declaration guide |
| Adds a login | App access. See app access instructions |
How should you roll out the update?
For production, use a staged rollout so a bug reaches only a fraction of users first. Staged rollouts apply to updates, which makes them ideal for exactly this situation. Read how staged rollout works for the steps and a suggested percentage plan.
What if something goes wrong?
| Problem | Action |
|---|---|
| Crash rate spikes | Halt the rollout, fix the bug, release a new version with a higher versionCode |
| Wrong key error | Use the original upload keystore or request a reset |
| Rejected update | Read the notice and fix the policy issue. See app rejection reasons |
| Account warning | Read what to do if your account is terminated |
Part of a series: this article is one chapter of Google Play Closed Testing: The Complete Guide. Start there for the full roadmap from setup to production.
Sources
- Android Developers: Version your app
- Google Play Console Help: Create and set up your app
- Google Play Console Help: Staged rollouts
How often should you update?
There is no Google rule for frequency. What matters is a rhythm you can keep. This table shows a sensible pattern for a small team.
| Type of update | Typical cadence | Checks |
|---|---|---|
| Critical bug fix | As soon as fixed and tested | Internal test, then a fast staged rollout |
| Small improvements | Every 2 to 4 weeks | Internal test plus a day or two at low percentage |
| Major features | Every few months | Internal and closed test, a full staged plan |
| Compliance changes (policy, API level) | Before Google's deadline | Read the Play Console message and test on the newest Android |
Update checklist
| Step | Done? |
|---|---|
| versionCode increased | ☐ |
| versionName updated | ☐ |
| Signed with the same upload keystore | ☐ |
| Installed as an update on a real phone | ☐ |
| Release notes written | ☐ |
| Declarations re-checked | ☐ |
| Staged rollout started at a small percentage | ☐ |
Frequent mistakes
- Forgetting to raise versionCode after a failed upload, then reusing it.
- Changing the signing key without a reset request.
- Updating the store listing text before the release reaches everyone.
- Skipping the Data safety update after adding a new SDK. See the Data safety guide.
- Shipping on Friday evening with nobody watching crash reports.
Frequently asked questions
Do I need a new versionCode for every update?
Yes. Google says each successive release must use a greater versionCode and you cannot upload one you already used. The maximum is 2100000000.
Do I need to sign updates with the same key?
You sign the bundle with your upload key. Play App Signing then signs the APKs users get with the app signing key, so users see updates from the same developer.
Should I test an update before releasing it?
Yes. Upload it to an internal or closed test first, then release to production or use a staged rollout.
Will users get the update immediately?
Not necessarily. Rollouts, device conditions and user settings affect when an update appears, and Google says full rollout may take time.
Do I need to redo my declarations on every update?
Only if your app changes affect them. Retake the content rating questionnaire when content or features change, and update the Data safety form when your data practices change.
Can I undo a bad update?
Google's staged rollout page offers halting a rollout and releasing a new fixed version. It does not describe reverting to an earlier version, so release a fixed bundle with a higher versionCode.
