Gradle Play Publisher
Gradle Play Publisher (GPP) is Android's unofficial release automation Gradle Plugin. It can do
anything from building, uploading, and then promoting your App Bundle or APK to publishing app
listings and other metadata.
## Project status: maintenance mode
Issues are ignored, but pull requests are not. If you need to get something done, submit a PR!
## Table of contents
1. [Quickstart guide](#quickstart-guide)
2. [Prerequisites](#prerequisites)
1. [Initial Play Store upload](#initial-play-store-upload)
2. [Signing configuration](#signing-configuration)
3. [Service Account](#service-account)
3. [Basic setup](#basic-setup)
1. [Installation](#installation)
2. [Authenticating Gradle Play Publisher](#authenticating-gradle-play-publisher)
4. [Task organization](#task-organization)
5. [Managing artifacts](#managing-artifacts)
1. [Common configuration](#common-configuration)
2. [Publishing an App Bundle](#publishing-an-app-bundle)
3. [Publishing APKs](#publishing-apks)
4. [Uploading an Internal Sharing artifact](#uploading-an-internal-sharing-artifact)
5. [Promoting artifacts](#promoting-artifacts)
6. [Handling version conflicts](#handling-version-conflicts)
6. [Managing Play Store metadata](#managing-play-store-metadata)
1. [Quickstart](#quickstart)
2. [Directory structure](#directory-structure)
3. [Publishing listings](#publishing-listings)
4. [Publishing in-app products](#publishing-in-app-products)
5. [Publishing in-app subscriptions](#publishing-in-app-subscriptions)
7. [Working with product flavors](#working-with-product-flavors)
1. [Disabling publishing](#disabling-publishing)
2. [Combining artifacts into a single release](#combining-artifacts-into-a-single-release)
3. [Using multiple Service Accounts](#using-multiple-service-accounts)
8. [Advanced topics](#advanced-topics)
1. [Using CLI options](#using-cli-options)
2. [Using HTTPS proxies](#using-https-proxies)
## Quickstart guide
1. Upload the first version of your APK or App Bundle using the
[Google Play Console](https://play.google.com/apps/publish)
2. [Create a Google Play Service Account](#service-account)
3. [Sign your release builds](https://developer.android.com/studio/publish/app-signing#gradle-sign)
with a valid `signingConfig`
4. [Add and apply the plugin](#installation)
5. [Authenticate GPP](#authenticating-gradle-play-publisher)
## Prerequisites
### Initial Play Store upload
The first APK or App Bundle needs to be uploaded via the Google Play Console because registering the
app with the Play Store cannot be done using the Play Developer API. For all subsequent uploads and
changes, GPP may be used.
### Signing configuration
To successfully upload apps to the Play Store, they must be signed with your developer key. Make
sure you have
[a valid signing configuration](https://developer.android.com/studio/publish/app-signing#gradle-sign).
### Service Account
To use GPP, you must create a service account with access to the Play Developer API:
1. If you don't already have one, create a GCP project for your app(s)
2. Enable the
[AndroidPublisher API](https://console.cloud.google.com/apis/library/androidpublisher.googleapis.com)
for that GCP project
3. Create a
[service account and key](https://console.cloud.google.com/apis/credentials/serviceaccountkey)
1. Make sure you're in the GCP project you used above (check the `project` query param in the
URL)
2. Select `New service account`
3. Give it a name and the Project Owner role (don't worry, we'll remove this later)
4. After creating the service account, find it in the list of all service accounts and use the 3
dots menu to `Manage keys`
5. From there, create a new key using the `Add key` menu (leave JSON selected)
4. Move the downloaded JSON credentials into your project and
[tell GPP about it](#authenticating-gradle-play-publisher)
5. Give your service account
[permissions to publish apps](https://play.google.com/console/developers/users-and-permissions)
on your behalf
1. Click `Invite new user`
2. Copy/paste the service account email (you can find it in the JSON credentials)
3. Don't touch the roles
4. Specify which apps the service account should have access to. In this example, GPP has full
access to testing tracks and app listings, but will be unable to make production releases:
6. Run `./gradlew bootstrapListing` or some other GPP task to validate your setup
7. Now that you've successfully created the connection between GCP and Google Play, you can remove
the Project Owner permissions
1. Go to your [IAM settings](https://console.cloud.google.com/iam-admin/iam)
2. Search for the service account you created
3. Click the edit icon (found at the end of the row)
4. In the permission selection panel that opens, click the trash icon to remove the owner role
5. Click save
## Basic setup
### Installation
Apply the plugin to each individual `com.android.application` module where you want to use GPP
through the `plugins {}` DSL:
Kotlin
```kt
plugins {
id("com.android.application")
id("com.github.triplet.play") version "4.1.1"
}
```
Groovy
```groovy
plugins {
id 'com.android.application'
id 'com.github.triplet.play' version '4.1.1'
}
```
Kotlin
```kt
buildscript {
repositories {
// ...
maven("https://oss.sonatype.org/content/repositories/snapshots")
}
dependencies {
// ...
classpath("com.github.triplet.gradle:play-publisher:5.0.0-SNAPSHOT")
}
}
```
Groovy
```groovy
buildscript {
repositories {
// ...
maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
}
dependencies {
// ...
classpath 'com.github.triplet.gradle:play-publisher:5.0.0-SNAPSHOT'
}
}
```
Kotlin
```kt
play {
// In a simple app, this play block is all you'll need. However, in an app with product flavors,
// the play block becomes a place to store default configurations. Anything configured in here
// will apply to all product flavors, that is, unless an override is supplied in the playConfigs
// block.
}
android {
// Suppose we have the following flavors
flavorDimensions("customer", "type")
productFlavors {
register("firstCustomer") { setDimension("customer") }
register("secondCustomer") { setDimension("customer") }
register("demo") { setDimension("type") }
register("full") { setDimension("type") }
}
playConfigs {
// Now, we can configure GPP however precisely is required.
// Configuration overrides occur in a cascading manner from most to least specific. That is,
// a property configured in a build type + flavor combo overrides that same property
// configured in a flavor combo, which overrides a build type combo, which in turn overrides
// the play block. Properties not configured are inherited.
register("firstCustomerFullRelease") { ... } // Build type + flavor
register("firstCustomer") { ... } // Flavor
register("release") { ... } // Build type
}
}
```
Groovy
```groovy
play {
// In a simple app, this play block is all you'll need. However, in an app with product flavors,
// the play block becomes a place to store default configurations. Anything configured in here
// will apply to all product flavors, that is, unless an override is supplied in the playConfigs
// block.
}
android {
// Suppose we have the following flavors
flavorDimensions 'customer', 'type'
productFlavors {
firstCustomer { dimension 'customer' }
secondCustomer { dimension 'customer' }
demo { dimension 'type' }
full { dimension 'type' }
}
playConfigs {
// Now, we can configure GPP however precisely is required.
// Configuration overrides occur in a cascading manner from most to least specific. That is,
// a property configured in a build type + flavor combo overrides that same property
// configured in a flavor combo, which overrides a build type combo, which in turn overrides
// the play block. Properties not configured are inherited.
firstCustomerFullRelease { ... } // Build type + flavor
firstCustomer { ... } // Flavor
release { ... } // Build type
}
}
```
Kotlin
```kt
android {
// ...
playConfigs {
register("myCustomVariantOrProductFlavor") {
enabled.set(true)
}
// ...
}
}
play {
enabled.set(false) // This disables GPP by default. It could be the other way around.
// ...
}
```
Groovy
```groovy
android {
// ...
playConfigs {
myCustomVariantOrProductFlavor {
enabled.set(true)
}
// ...
}
}
play {
enabled.set(false) // This disables GPP by default. It could be the other way around.
// ...
}
```
Kotlin
```kt
// Don't commit any changes by default
play.commit.set(false)
android {
// ...
playConfigs {
register("someFlavorThatWillCommit") {
// Pick a flavor that will commit the changes prepared by all flavors
commit.set(true)
}
}
}
afterEvaluate {
// Now make sure the tasks execute in the right order
val intermediateTasks = listOf(
"publishSomeFlavor2Release[Apk/Bundle]",
"publishSomeFlavor3Release[Apk/Bundle]",
...
)
// The commit flavor task must run last so the other tasks can build up changes to commit
tasks.named("someFlavorThatWillCommitRelease[Apk/Bundle]").configure {
mustRunAfter(intermediateTasks)
}
}
```
Groovy
```groovy
// Don't commit any changes by default
play.commit.set(false)
android {
// ...
playConfigs {
someFlavorThatWillCommit {
// Pick a flavor that will commit the changes prepared by all flavors
commit.set(true)
}
}
}
afterEvaluate {
// Now make sure the tasks execute in the right order
def intermediateTasks = [
"publishSomeFlavor2Release[Apk/Bundle]",
"publishSomeFlavor3Release[Apk/Bundle]",
...
]
// The commit flavor task must run last so the other tasks can build up changes to commit
tasks.named("someFlavorThatWillCommitRelease[Apk/Bundle]").configure {
mustRunAfter(intermediateTasks)
}
}
```
Kotlin
```kt
android {
// ...
playConfigs {
register("firstCustomer") {
serviceAccountCredentials.set(file("customer-one-key.json"))
}
register("secondCustomer") {
serviceAccountCredentials.set(file("customer-two-key.json"))
}
}
}
```
Groovy
```groovy
android {
// ...
playConfigs {
firstCustomer {
serviceAccountCredentials.set(file('customer-one-key.json'))
}
secondCustomer {
serviceAccountCredentials.set(file('customer-two-key.json'))
}
}
}
```