Gradle Play Publisher: Android Release Automation
/gradle-play-publisher
Gradle Play Publisher is a Gradle plugin that pushes Android App Bundles and APKs from a build script straight to the Google Play Console, handling track promotion and store listing metadata along the way. It has 4308 GitHub stars. Reach for it if your release process already runs through Gradle and CI; skip it if you need active support for edge cases, since the project is in maintenance mode and issues go unanswered.
What is Gradle Play Publisher?
Gradle Play Publisher, referred to in its own docs as GPP, is a Gradle plugin that automates uploading and promoting Android App Bundles or APKs to the Google Play Store and can also push listing metadata like descriptions and screenshots. It runs as Gradle tasks named after Android Gradle Plugin conventions, such as publishBundle or publishApk, so it fits into an existing Android build instead of replacing it.
Key Features for Android Publishing
- โUploads and promotes both App Bundles and APKs to any track (internal, alpha, beta, production, or a custom one) through Gradle tasks like publishBundle and publishApk.
- โNames Gradle tasks using an [action][Variant][Thing] pattern, matching the Android Gradle Plugin's own convention, so a paid flavor gets a publishPaidReleaseBundle task automatically.
- โManages Play Store listing metadata (descriptions, contact details, screenshots) from files under src/[sourceSet]/play, and merges missing translations from the default language.
- โReads per-track release notes from release-notes/[language]/[track].txt files, falling back to the previous release's notes when none are found.
- โUploads Internal Sharing artifacts and can install them directly to a connected device with installReleasePrivateArtifact.
- โResolves version-code conflicts automatically using a resolutionStrategy of IGNORE or AUTO instead of failing the build.
- โAuthenticates through a service account JSON file, an ANDROID_PUBLISHER_CREDENTIALS environment variable, or Application Default Credentials with optional service account impersonation.
Strengths
- โTies release publishing to the same Gradle tasks that build the app, so a CI job runs one command instead of scripting the Play Console separately.
- โGenerates a task per product flavor automatically, following the Android Gradle Plugin's own naming convention.
- โCovers more than artifact upload: release notes, release names, in-app products, subscriptions, and store listing text are all scriptable.
- โThree authentication paths (service account file, environment variable, or Application Default Credentials) cover local development and CI without hardcoding secrets.
- โMIT licensed, with no restriction on using it in a commercial Android project.
Project Status and Limitations
- โณThe project is in maintenance mode: the maintainers don't respond to bug reports, and per the README, a fix only lands if someone contributes it as a pull request.
- โณGPP can't handle an app's very first release. That initial APK or App Bundle still has to go up through the Google Play Console by hand, since app registration isn't exposed through the Play Developer API.
- โณRelease notes are capped at 500 characters and release names at 50 characters, hard limits set by the Play Store rather than GPP.
- โณApp Bundles don't need a separate mapping.txt, because that mapping data already lives inside the bundle itself; the workflow described here only matters for APK builds.
- โณThe exact per-language listing character limits (title, short description, full description) aren't included in the documentation reviewed here, so check the Play Console before finalizing copy.
Alternatives for Android Deployment Automation
Frequently Asked Questions
Gradle Play Publisher is in maintenance mode: the README says bug reports go unanswered, while a fix still needs to arrive as a contributed pull request.
Gradle Play Publisher requires an app already uploaded once through the Google Play Console, a valid release signing configuration, and a Google Cloud service account with the AndroidPublisher API enabled and publishing permissions in the Play Console.
Gradle Play Publisher authenticates with a service account JSON key set via serviceAccountCredentials, an environment variable named ANDROID_PUBLISHER_CREDENTIALS, or Application Default Credentials with optional service account impersonation.
Gradle Play Publisher cannot upload an app's first version. The README requires that initial upload go through the Google Play Console because app registration isn't available through the Play Developer API; GPP handles every upload after that.
GPP can publish listing text and contact details, in-app product and subscription data, and screenshots, all pulled from files under a project's src/[sourceSet]/play directory and merged across languages and product flavors.
Release notes managed through GPP are capped at 500 characters per the README, and a separate release-name field is capped at 50 characters.
The problem it solves
Publishing an Android update means juggling two separate systems: the Gradle build that produces the App Bundle or APK, and the Google Play Console where that artifact, its release notes, and its store listing actually go live. Doing the Play Console half by hand for every release, especially across several product flavors and tracks, means someone re-uploading files and retyping release notes each time. Gradle Play Publisher wires the Play Developer API into the same Gradle tasks that already build the app, so upload and promotion run as part of the build instead of a separate manual pass.
Best use cases
- โขA CI pipeline that needs to push a new internal or alpha build to testers on every merge, without anyone touching the Play Console by hand.
- โขTeams running several product flavors that each need their own track and release notes, since GPP generates a task per flavor automatically.
- โขPromoting a build already live on one track to another, like moving a beta release to production with a staged rollout percentage, without re-uploading the artifact.
- โขKeeping store listing text, screenshots, and in-app product metadata under version control instead of hand-edited in the Play Console.
How to install / try
Apply the plugin per module in build.gradle(.kts), alongside com.android.application. Then add id("com.github.triplet.play") version "4.1.1" to the plugins {} block. Three things need to be true before that does anything useful: the app's first APK or App Bundle was already uploaded once through the Google Play Console, since GPP can't do that part; the release build has a valid signing configuration; and a Google Cloud service account exists with the AndroidPublisher API enabled and a downloaded JSON key. Snapshot builds of the next version, currently 5.0.0-SNAPSHOT, are published to Sonatype's snapshots repository for anyone tracking development ahead of a tagged release.
How to use
Point GPP at the service account key with play { serviceAccountCredentials.set(file("path/to/your-key.json")) }, or skip committing the file and set an environment variable named ANDROID_PUBLISHER_CREDENTIALS instead. From there, ./gradlew publishBundle uploads and publishes an App Bundle, ./gradlew publishApk does the same for an APK, and ./gradlew promoteArtifact moves an existing release from one track to another using a fromTrack/promoteTrack pair or matching CLI flags. Run ./gradlew bootstrapListing once to pull the current Play Store listing into the project as a starting point, then ./gradlew publishListing to push edited metadata back up. Settings like track, releaseStatus, and userFraction, a staged rollout percentage that defaults to 0.1 (10%), all live in the play {} block.
Who should try it โ and who should skip
Try Gradle Play Publisher if you're already building Android apps with Gradle and want release notes, track promotion, and store metadata to live in your repository instead of the Play Console UI. It fits teams with several flavors or a CI pipeline that already runs Gradle tasks. Skip it if you're not comfortable reading source or opening a pull request when something breaks, since the README is explicit that issues go unanswered, or if you haven't done the one-time manual first upload and service account setup the plugin depends on.
Related repositories
Want a second opinion on gradle-play-publisher?
Ask an AI that can read this page โ one click and you get its take on gradle-play-publisher.