Publish to Google Play
Upload a signed App Bundle to a Google Play track with a staged rollout and release notes.
Upload a successful Android build’s signed App Bundle to the Google Play
track you choose. Set it up once in the pipeline’s Publishing tab, as
below, or give each .oore.yaml workflow its own track and service account;
see Publish per workflow. The runner that built the
app uploads it from its own host, so the bundle never passes through the
daemon.
What you need
- App developer, maintainer, instance admin, or instance owner access. Storing a shared instance secret needs instance admin or owner access.
- An app that already exists in Play Console, with one release uploaded by hand. Google Play does not let the API create an app or upload its first release. Deliver to testers on Google Play walks through that first upload.
- A pipeline that builds a release App Bundle and signs it with your upload key, from the pipeline’s signing settings (Add Android signing) or an Android keystore in the app’s signing library.
- A Google Cloud service account with a JSON key, invited in Play Console under Users and permissions with release permissions for the app.
- Outbound HTTPS from the runner host to
oauth2.googleapis.comandandroidpublisher.googleapis.com. The daemon host needs the same for credential checks and rollout controls.
1. Store the service account key as a secret
Store the whole JSON key file as a secret named PLAY_SERVICE_ACCOUNT. When
all your apps are in one Play Console developer account, store it once as an
instance secret: open Settings > Secrets and credentials and, under
Google Play service account, select Add service account. New
pipelines then choose it on the Publishing tab without another upload. A
app or pipeline secret with the same name overrides it.
From the API, any scope works. An app secret is shared by all of the app’s pipelines:
jq -n --rawfile value play-service-account.json \
'{name: "PLAY_SERVICE_ACCOUNT", value: $value}' |
curl -X POST "$OORE_URL/v1/projects/$PROJECT_ID/secrets" \
-H "Authorization: Bearer $OORE_TOKEN" \
-H 'Content-Type: application/json' \
-d @-See Use secrets in a pipeline for scopes and rotation.
2. Configure publishing
- Open the pipeline and its Publishing tab.
- Under Google Play, turn on Upload to Google Play after each successful build.
- Under Credentials, choose the secret for Service account key.
- Under Release, choose the Track and the Rollout: Full rollout, Staged rollout with an Initial rollout (%), or Draft. Release notes sends the version’s release notes in the Language of the notes, or Files in the repository from a folder.
- Under Advanced, enter the app’s application ID in Expected package, and choose Pre-flight checks: whether Google Play’s validation of the release stops the upload, only warns, or is skipped.
- Select Turn on Google Play publishing, or Save changes when publishing was already on.
The readiness list at the top of the section shows what is still missing,
such as release signing or an App Bundle build. While uploads are on and the
Android command is Oore’s default, Oore builds an App Bundle as well as the
APK. An Android command override must build the bundle itself, such as
flutter build appbundle --release.
For automation, send the same settings with the Update Google Play publish settings operation:
curl -X PUT "$OORE_URL/v1/pipelines/$PIPELINE_ID/publish/google-play" \
-H "Authorization: Bearer $OORE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"enabled": true,
"service_account_secret": "PLAY_SERVICE_ACCOUNT",
"track": "production",
"rollout_percent": 5,
"release_notes": "changelog"
}'The response includes service_account_secret_present, which is false until
the named secret exists in a scope this pipeline can see.
| Field | Default | Meaning |
|---|---|---|
enabled | false | Upload after each successful build of this pipeline. |
service_account_secret | Name of the secret holding the service account JSON key. | |
track | internal, closed, open, production, or the name of a custom closed track. closed is Play’s alpha and open is beta. | |
package_name | AAB | Expected application id. When set, a bundle for a different package fails the upload. |
rollout_percent | 100 | Initial staged rollout. Below 100 creates an in-progress release for that share of users. The internal track does not support staged rollouts. |
draft | false | Create a draft release instead of rolling out. |
release_notes | none | changelog (the app version’s release notes) or repo_files. none behaves like changelog: a version without notes sends none. |
release_notes_locale | en-US | Language the version’s release notes are sent under. |
release_notes_dir | For repo_files: a repository directory with one <locale>.txt file per language, such as release-notes/en-US.txt. | |
upload_mapping | true | Upload build/app/outputs/mapping/<variant>/mapping.txt when the build produced it. |
in_app_update_priority | In-app update priority, 0 to 5. | |
preflight | auto | What a failed edits.validate check does before the commit: auto, block, warn or off. auto blocks once the app has had a release on Play, and warns before that. |
Release notes longer than Play’s 500-character limit are shortened. The build’s list of commits and their authors never goes to Play; see Release notes and changes.
3. Test the credentials
On the pipeline’s Publishing tab, select Test credentials under Credentials to check the key without running a build. The daemon exchanges the key for a token, then opens a Play edit for the app and discards it, which needs the same Play Console access as an upload and changes nothing. A failure shows Google’s reason, such as a rejected key or a service account that is not invited for the app.
The check opens the app named in the Expected package field. When that is
empty, it uses the saved package_name, then the package of the pipeline’s
latest Google Play release. From the API, use the
Test Google Play credentials
operation:
curl -X POST "$OORE_URL/v1/pipelines/$PIPELINE_ID/publish/google-play/test-credentials" \
-H "Authorization: Bearer $OORE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"service_account_secret": "PLAY_SERVICE_ACCOUNT", "package_name": "com.example.app"}'The response has ok, a message with what passed or the exact failure, and
the key’s service_account_email.
Oore keeps the pipeline’s latest check, and the Publishing tab shows it with
when it ran. It is returned as last_credentials_check with the Google Play
publish settings until the key behind its secret name changes. Rotating the
secret, deleting it, or adding a narrower secret with the same name clears it.
4. Run a build
After the build, signing and artifact steps succeed, the runner adds a
Upload to Google Play step (publish-play) that:
- Picks the release App Bundle under
build/app/outputs/bundleand reads its package name,versionCodeandversionName. - Exchanges the service account key for an access token.
- Reads the version codes Play already holds and stops if the bundle’s
versionCodeis not higher than the highest one on the target track, or was already uploaded. The error names both numbers and says how to fix it: bump the number after+inpubspec.yaml, or raisebuild_number_offsetwhen the build passes--build-number=$OORE_VERSION_CODE; see Version codes. - Opens a Play edit, uploads the bundle and
mapping.txt, sets the track release with the configured status and rollout, and commits the edit.
If any earlier step fails, nothing is uploaded. If a Play call fails, the Upload to Google Play step fails with the Play API’s error text, and the edit is discarded so nothing is left half-staged in Play Console.
A release Google Play holds or refuses says what is wrong in one sentence when Oore knows the refusal, such as changes waiting to be sent for review or a service account without release access, with a button to the Play Console page that fixes it. A rollout Oore runs draws its schedule as steps, with where it is now, when the next raise happens and the crash rate that halts it.
After fixing the cause, such as a missing Play Console permission, retry the upload to upload the stored bundle without building again.
Verify the result
- The build shows a succeeded Upload to Google Play step, and its log names the track and rollout.
- Play Console shows the version on the chosen track at the chosen rollout.
- The audit log has a
store_upload_completedentry for the build.
Publish per workflow
With a .oore.yaml version 2 file, each workflow can publish differently
from the same pipeline, such as beta to the internal track and release to
production:
signing:
android: upload-key # an Android keystore in the project's signing library
workflows:
release:
targets:
android:
build: flutter build appbundle --release
publish:
play:
track: production
rollout: 0.05
service_account: PLAY_SERVICE_ACCOUNTservice_accountnames the secret with the JSON key. With it, the upload needs no Google Play settings in the pipeline. Without it, turn the pipeline’s Google Play upload on as in step 2.signing.androidnames the keystore that signs the bundle, from the app’s signing library. Without it, the pipeline’s Android signing applies.- To stop one workflow’s uploads without a commit, open the pipeline’s Workflows tab, select Settings on the workflow, and turn Publishing off.
oore pipeline validate --project "$PROJECT_ID" checks that the keystore and
the secret exist in the app before you push, and oore pipeline plan
prints the track, identity and secret each workflow uses. Every field is in
Publish, and the per-workflow
switches in Workflow settings.
Store listing from the repository
To keep the title and descriptions in Git, set Store listing from the
repository under the pipeline’s Google Play advanced settings to a
directory in fastlane’s layout, such as fastlane/metadata/android:
fastlane/metadata/android/
en-US/
title.txt # at most 30 characters
short_description.txt # at most 80 characters
full_description.txt # at most 4000 characters
video.txt # a YouTube URL
de-DE/
short_description.txtEach upload sends the listing in the same Play edit as the bundle, so the listing changes when the release does. A file you leave out keeps what Play Console has. A file over Play’s limit fails the upload before anything is sent, so a title is never cut short. Screenshots and graphics are not uploaded; change them in Play Console.
Store health on Insights
Insights lists every app a pipeline publishes to Google Play: each package named in a pipeline’s Expected package, or reached by a passing Test credentials check, and each package Oore has released. A pipeline that sets neither and has not released yet does not name an app, so Insights cannot list it; fill in Expected package to add it.
For each app, the daemon reads the user-perceived crash rate and ANR rate over the last 28 days from the Play Developer Reporting API, with the top crash and ANR clusters. Insights shows them against Google Play’s bad-behavior thresholds of 1.09% and 0.47%. The numbers refresh every six hours with the service account of the pipeline that made the newest release, or, before the first release, the pipeline whose Google Play settings were saved last.
The service account needs View app information for the app in Play
Console, and the daemon host needs outbound HTTPS to
playdeveloperreporting.googleapis.com. Without them, Insights shows why the
numbers could not be read. A failed read is retried after 15 minutes; after
fixing access, choose Check stores in Store health on Insights to read the store at once.
Troubleshooting
The Google Play upload fails because the version code is not higher
The message names both numbers. Bump the number after + in
pubspec.yaml’s version above the highest one on Google Play, in a
commit, and run a new build. If the pipeline passes
--build-number=$OORE_VERSION_CODE, raise Build number offset instead.
The Google Play upload fails with a Play API error
Fix the cause, such as a missing Play Console permission, then retry the upload. The stored bundle is uploaded again without rebuilding.
The release is Blocked with “send it for review in Play Console”
Google holds some changes until you send them for review yourself, and the commit only succeeds with that hold. Open Publishing overview in Play Console and select Send changes for review, then choose Mark sent for review on the release. When Google rejects it, choose Mark rejected.
A rollout shows “No schedule”
The release was made in Play Console, not by Oore, so Oore does not raise it. Raise it in Play Console, or choose Manage rollout with Oore on the release to attach the pipeline’s rollout schedule. The confirmation lists each step Oore will take and when. Stop scheduled steps detaches it again.
Test credentials fails
The message gives Google’s reason. Invite the service account for this app in Play Console, wait a few minutes for Google to process the invitation, and test again.
Limits
- One App Bundle per publish. A pipeline that builds several release flavors fails with a list of the bundles it found.
Next step
Promote builds between environments to move a tested version from internal testing to production without rebuilding it.