How to See Uploads in Google Play Plugin
Enables Jenkins to manage and upload Android app files (AAB or APK) to Google Play.
Features
- Uploading Android App Bundle (AAB) or APK files to a release track on Google Play
- This includes apps which use Multiple APK back up
- ProGuard
mapping.txtand native debug symbols tin can likewise be associated with each app file, for deobfuscating crash dumps - APK expansion (.obb) files can also be uploaded
- With the option to re-utilize expansion files from existing APKs, e.1000. for patch releases
- App files from previous releases can be included when creating a release
- The update priority can be set up, if using in-app updates
- Release notes can exist added, for various languages
- Staged rollout of apps to any release track
- Uploading app files without yet rolling out to users, creating a typhoon release
- Assigning apps to internal, alpha, beta, product, or custom release tracks
- This includes a build step for moving existing versions to a dissimilar track, or updating the rollout pct
e.k. Y'all can upload an blastoff in one job, then afterward have another job promote it to beta
- This includes a build step for moving existing versions to a dissimilar track, or updating the rollout pct
- Uploading app files to Internal App Sharing
- Changing the Jenkins build event to failed if the configuration is bad, or uploading or moving app files fails for some reason
- Every configuration field supports variable and token expansion, allowing release notes to be dynamically generated, for example
- Integration with the Google OAuth Credentials Plugin, and then that Google Play credentials can be entered once globally, stored securely, and shared betwixt jobs
- Multiple Google Play accounts are also supported via this machinery
Requirements
Jenkins
Jenkins version 2.222.4 or newer is required.
Google Play publisher account
For the initial setup simply, you must accept access to the Google business relationship which owns the Google Play publisher account.
This is required to enable API access from Jenkins to your Google Play account.
Note that having admin access to the Google Play Console is not enough; you need the account owner.
You can come across who the account owner is under Settings → Programmer business relationship → Account details in the Google Play Console.
Please note
- The app beingness uploaded must already exist in Google Play; you cannot utilise the API to upload brand new apps
Parcel size warnings
If you endeavor to upload an AAB file to Google Play (including manually via the Google Play Console), and its size is perhaps 100MB+, information technology may give you a warning:
The installation of the app bundle may be besides large and trigger user warning on some devices […] this needs to be explicitly best-selling
Unfortunately, this "user warning" that may be shown, presumably when a user installs your app from Google Play, does not appear to be documented. Therefore this plugin automatically "acknowledges" that alert on Google Play on your behalf when uploading any AAB files, regardless of their size, then yous should not run across whatsoever errors.
If you practice see see whatever unexpected behaviour related to uploading bundles, or warnings appearing for end users, delight let us know.
Setup
One-time: Ready upwards Google Play credentials
One time you take this plugin installed, the following initial setup process is demonstrated in this video: https://www.youtube.com/picket?v=txdPSJF94RM (note that Google has changed the Google API Console (at least twice) since this video was recorded; steps iii–13 in the "Create Google service account" section below take the updated info).
Create Google service account
To enable automated access to your Google Play account, yous must create a service business relationship:
- Sign in to the Google Play Console equally the programmer account possessor
- You can decide the account owner on the Account details folio
- Select Settings → Developer account → API access
- Under Service Accounts, click "Create Service Business relationship"
- Follow the link to the Google API Console
- Click the "Create service account" push
- Give the service business relationship any proper noun you lot similar, due east.g. "Jenkins"
- Cull Service Accounts > Service Business relationship User for the "Role" field
- Enable "Replenish a new private key"
- Choose "JSON" as the key type (P12 works every bit well, but JSON is a fiddling simpler)
- Click the "Save" button
- Note that a .json file is downloaded, named something similar "api-xxxxxxxxx-xxxxx-xxxx.json"
- Close the dialog that appears
- Copy the email address of the new user (something like "jenkins@api-xxxxxxxxx-xxxxx-xxxx.iam.gserviceaccount.com")
- Yous tin now close the page
Assign permissions to the service account
- Return to the Google Play Console page
- Click "Washed" on the dialog
- Note that the service business relationship has been associated with the Google Play publisher account
If it hasn't, follow these additional steps before continuing:- Click "Users & permissions" in the bill of fare
- Click "Invite new user"
- Paste in the e-mail address you copied above
- Continue from footstep 5
- Click the "Grant access" button for the account (east.g. "jenkins@api-xxxxxxxxx-xxxxx-xxxx.iam.gserviceaccount.com")
- Ensure that at least the following permissions are enabled:
- View app data — this is required for the plugin to function
- Manage production releases — optional, if y'all want to upload APKs to product
- Manage testing rail releases — optional, if you want to upload APKs to alpha, beta, internal, or custom examination tracks
- Click "Add user" (or "Send invitation", equally advisable)
- Y'all can now log out of the Google Play publisher account
Add the service account credentials to Jenkins
Manually
- Navigate to your Jenkins instance
- Select "Credentials" from the Jenkins sidebar, at the elevation-level, or from within the binder where the credential should live
- Choose a credentials domain and click "Add Credentials"
- From the "Kind" drop-down, choose "Google Service Business relationship from private fundamental"
- Enter a meaningful proper name for the credential, every bit you'll need to select it during build configuration, or enter it into your Pipeline configuration
- Choose the "JSON cardinal" type
- Upload the .json file that was downloaded past the Google API Console
- Click "OK" to create the credential
Using Configuration as Code
If you're using the Configuration as Code plugin to gear up your credentials automatically, you can practise something like this:
credentials: organization: domainCredentials: - credentials: - googleRobotPrivateKey: projectId: 'Google Play' serviceAccountConfig: json: # Optional filename: 'my-gp-account.json' # The contents of your .json file from Google Play, encoded every bit base 64, e.g.: # $ cat api-xxxxxxxxx-xxxxx-xxxx.json | base64 - # You lot can also provide an environs variable with the aforementioned content, to avoid having information technology in this file secretJsonKey: 'eyJjbGllbnRfZW1haWwiOiJqZW5raW5z […]' Whether done manually or automatically, Jenkins now has the required credentials and permissions in guild to publish to Google Play.
One time you've set up a job (see the next department) and confirmed that uploading works, either delete the downloaded JSON file or ensure that it'south stored somewhere secure.
Per-task configuration
Freestyle task configuration
Creating a release by uploading app bundles or APKs
The following job setup process is demonstrated in this video: https://www.youtube.com/lookout man?5=iu-bLY9-jkc
- Create a new free-style software project
- Ensure, via whatever build steps you need, that the file(south) you lot want to upload volition exist available in the build's workspace
- Add the "Upload Android AAB/APK to Google Play" post-build action
- Select the credential name from the drop-downward list
- The credential must belong to the Google Play business relationship which owns the app to be uploaded
- Enter paths and/or patterns pointing to the AAB or APKs to exist uploaded
- This can be a glob blueprint, east.g.
'build/**/*-release.apk', or a filename, both relative to the root of the workspace - Multiple patterns or filenames can be entered, if separated by commas
- If nothing is entered, the default is
'**/build/outputs/**/*.aab, **/build/outputs/**/*.apk'
- This can be a glob blueprint, east.g.
- Enter the release rails to which the files should be assigned
- This can be a congenital-in track like
'production', a testing track like'beta', or a custom rails name - Note that custom track names are case-sensitive (though the plugin will attempt to make up one's mind the correct track)
- This can be a congenital-in track like
- Specify a rollout percentage between 0 and 100%
- If 100% is entered, the app volition be immediately rolled out to all users on the called release track
- If 0% is entered, the given file(s) will be uploaded as a typhoon release, leaving any existing rollout unaffected
- Optionally cull "Add linguistic communication" to acquaintance release notes with the uploaded file(southward)
- You lot add together entries for as many or as few of your supported language as y'all wish, but each linguistic communication must already have been added to your app, under the "Store Listing" section in the Google Play Console.
APK expansion files
You can optionally add up to ii expansion files (main + patch) for each APK beingness uploaded.
A list of expansion files can be specified in the same way as APKs, though notation that they must be named in the format [main|patch].<apk-version>.<packet-name>.obb.
You can also enable the "Re-use expansion files from existing APKs where necessary" choice, which will automatically the nearly-contempo expansion files to newly uploaded APKs.
Similarly, if yous desire to utilize the aforementioned expansion file(s) to multiple APKs existence uploaded, yous tin do and so. Name the expansion file(s) co-ordinate to the everyman version lawmaking being uploaded: the expansion file will and then be uploaded, and practical to the remaining APKs with higher version codes.
See the inline assist for more details.
Retaining existing version codes for new releases
You tin optionally retain app files from a previous release in the release that volition be created past this build step.
For example, if y'all have a Wearable Bone app file already released, but during a build y'all only need to upload new mobile app files, you tin enter the version lawmaking of the Wear Os app file to retain it for this new release, rather than having to upload it again here.
Any version codes entered in the "Additional app files to include" field will be assigned to the specified release track forth with the uploaded app files.
Uploading an app bundle or APK to Internal App Sharing
The Internal App Sharing feature of Google Play enables you to upload a single AAB or APK file for use by a restricted set of people, which tin can be hands installed by opening a URL on an Android device.
You lot can utilise this feature with the "Upload Android AAB/APK to Google Play" build step by setting the release rail name to internal-app-sharing. In this case, no other configuration is necessary other than the Google Play account, and optionally settings the files pattern. Note that this is different from uploading to the internal release rail.
Upon successful upload, the app installation URL returned past Google Play will be output to the build console log.
Moving existing app versions to some other release track
If you have already uploaded an app to the alpha track (for case), y'all tin later use Jenkins to re-assign that version to the beta or production release track.
Nether the "Build" department of the task configuration, add the "Move Android apps to a different release rails" build step and configure the new release rail. By setting the rollout percent to 0%, y'all have the option of creating a draft release — i.e. the app files are assigned to a new release track, but not even so made bachelor to users.
You can tell Jenkins which version codes should be moved past either entering the values direct, or by providing AAB or APK files, from which the plugin will read the application ID and version codes for y'all.
Pipeline job configuration
Equally of version 1.5, this plugin supports the Pipeline Plugin syntax.
You can generate the required Pipeline syntax via the Snippet Generator, just some examples follow.
Note that you should avoid using multiple instances of these steps in a parallel block, as the Google Play API merely allows one concurrent "edit session" to exist open at a fourth dimension.
Creating a release by uploading app bundles or APKs
The androidApkUpload build footstep lets yous upload Android App Bundle (AAB) or APK files.
| Parameter | Type | Example | Default | Description |
|---|---|---|---|---|
| googlePlayCredentialsId | string | 'Google Play creds' | (none) | Name of the Google Service Account credential created in Jenkins |
| filesPattern | cord | 'release/my-app.aab' | '**/build/outputs/**/*.aab, **/build/outputs/**/*.apk' | Comma-separated glob patterns or filenames pointing to the app files to upload, relative to the root of the workspace |
| trackName | string | 'internal' | (none) | Google Play track to which the app files should be published; or internal-app-sharing to upload directly to Internal App Sharing |
| releaseName | string | 'i.2.3' | (none) | Name used to place this release in the Google Play Console. If not set, Google Play will employ the app version name |
| rolloutPercentage | string | 'one.five' | (none) | The rollout percentage to assault the track; utilize 0% to create a draft release |
| (deprecated) | number | one.5 | (none) | (deprecated, but however supported; prefer rolloutPercentage instead — it takes priority if both are defined) |
| deobfuscationFiles Pattern | string | '**/mapping.txt' | (none) | Comma-separated glob patterns or filenames pointing to ProGuard mapping files to associate with the uploaded app files |
| nativeDebugSymbolFiles Pattern | cord | '**/symbols.naught' | (none) | Comma-separated glob patterns or filenames pointing to native debug symbol files to associate with the uploaded app files |
| expansionFilesPattern | string | '**/*.obb' | (none) | Comma-separated glob patterns or filenames pointing to expansion files to acquaintance with the uploaded APK files |
| usePreviousExpansion FilesIfMissing | boolean | false | true | Whether to re-use the existing expansion files that have already been uploaded to Google Play for this app, if whatever expansion files are missing |
| additionalVersionCodes | cord | '101, 102' | (none) | Version codes of existing app files which should be included in the new release being created |
| inAppUpdatePriority | string | 'one' | '0' | Priority of this release, used by the Google Play Core in-app update feature |
| recentChangeList | list | (see beneath) | (empty) | List of recent alter texts to associate with the upload app files |
The googlePlayCredentialsId, trackName, and rolloutPercentage parameters are mandatory, e.thousand. a minimal configuration would exist:
androidApkUpload googleCredentialsId: 'My Google Play business relationship' , trackName: 'product' , rolloutPercentage: '100' This volition find whatsoever app files in the workspace matching the design **/build/outputs/**/*.aab, **/build/outputs/**/*.apk, upload them to the Production track, and brand them bachelor to 100% of users.
Or if uploading a file to Internal App Sharing on Google Play, so only the credentials are required, assuming that a single AAB or APK file is establish in the build workspace:
androidApkUpload googleCredentialsId: 'My Google Play account' , trackName: 'internal-app-sharing' A more complete example:
androidApkUpload googleCredentialsId: 'My Google Play business relationship' , filesPattern: '**/build/outputs/**/*.aab' , trackName: 'dogfood' , rolloutPercentage: '25' , releaseName: 'Examination build ({versionCode})' , deobfuscationFilesPattern: '**/build/outputs/**/mapping.txt' , nativeDebugSymbolFilesPattern: '**/build/outputs/**/native-debug-symbols.zip' , additionalVersionCodes: '101, 102' , inAppUpdatePriority: 'ii' , recentChangeList: [ [linguistic communication: 'en-GB' , text: "Please test the changes from Jenkins build ${env.BUILD_NUMBER} ." ], [language: 'de-DE' , text: "Bitte die Änderungen vom Jenkins Build ${env.BUILD_NUMBER} testen." ] ] To upload APKs and their expansion files, reusing those from the previous upload where possible:
androidApkUpload googleCredentialsId: 'My Google Play account', filesPattern: '**/*.apk', expansionFilesPattern: '**/patch.obb', usePreviousExpansionFilesIfMissing: true Updating release tracks with existing app versions
The androidApkMove build footstep lets you movement existing Android app versions (whether AAB or APK) to another release rails, and/or update the rollout percentage.
| Parameter | Type | Example | Default | Description |
|---|---|---|---|---|
| googlePlayCredentialsId | string | 'Google Play creds' | (none) | Name of the Google Service Account credential created in Jenkins |
| trackName | string | 'internal' | (none) | Google Play release rails to update with the given app versions |
| releaseName | string | '1.2.3' | (none) | Name used to identify this release in the Google Play Console. If not set, Google Play will use the app version proper noun |
| rolloutPercentage | string | '1.5' | (none) | The rollout percentage to set on the given release track; use 0% to create a draft release |
| (deprecated) | number | ane.5 | (none) | (deprecated, merely still supported; prefer rolloutPercentage instead — it takes priority if both are divers) |
| fromVersionCode | boolean | true | false | If true, the applicationId and versionCodes parameters will be used. Otherwise the filesPattern parameter will be used |
| applicationId | string | 'com.example.app' | (none) | The application ID of the app to update |
| versionCodes | string | '1281, 1282, 1283' | (none) | Comma-separated list of version codes to assail the given release track |
| filesPattern | cord | 'release/my-app.aab' | '**/build/outputs/**/*.aab, **/build/outputs/**/*.apk' | Comma-separated glob patterns or filenames pointing to the files from which the application ID and version codes should be read |
| inAppUpdatePriority | string | 'ane' | '0' | Priority of this release, used by the Google Play Core in-app update characteristic |
The googlePlayCredentialsId, trackName, and rolloutPercentage parameters are mandatory, plus either an application ID and version lawmaking(s), or AAB or APK file(due south) to read this information from.
For case, this would motion the given versions to the production track, and make them available to 100% of users:
androidApkMove googleCredentialsId: 'My Google Play account' , trackName: 'production' , rolloutPercentage: '100' , applicationId: 'com.example.app' , versionCodes: '1281, 1282, 1283' Or moving versions from blastoff (for example), to 50% of beta users, figuring out which application ID and version codes to apply, based on the APK files in the workspace:
androidApkMove googleCredentialsId: 'My Google Play account' , trackName: 'beta' , rolloutPercentage: 'fifty' , fromVersionCode: imitation, filesPattern: '**/*.apk' Or, say the electric current production release is rolled out to 10% of users, and we desire to expand the rollout to 25% of users:
androidApkMove googleCredentialsId: 'My Google Play account' , trackName: 'production' , rolloutPercentage: '25' , applicationId: 'com.case.app' , versionCodes: '1281, 1282, 1283' Setting the release name
You can optionally set the release proper name, used to identify a particular release in the Google Play Console. This isn't visible to end users.
If this selection is not used, Google Play will set the release name to the versionName of the app file being uploaded, for example: "1.two.34".
When uploading app files and setting a release proper noun value, whatever instances of {versionCode} or {versionName} in the value will be replaced at build fourth dimension by the respective value from the app file beingness uploaded. If multiple app files are existence uploaded, the values from the file with lowest versionCode will be used.
For example, entering releaseName: "Release v{versionName}_${env.GIT_COMMIT}" in a Pipeline could yield a release name on Google Play something like "Release v1.2.34_b2c3d3e4".
Backwards-compatibility
Version 3.0
Version 3.0 of the plugin deprecated some parameters used by the build steps, just they will remain supported for the foreseeable future:
- For Pipeline,
apkFilesPatternis deprecated —filesPatternshould exist used instead
In improver, version 3.0 introduced the default values shown in the tables above, so those parameters tin optionally now be omitted.
Version 4.0
NOTE: This version makes it mandatory to configure a release track name, and the rollout per centum.
In guild to avert unintentionally publishing to Production — if you forget to provide a track name, or use a string parameter for the track name only accidentally leave it empty, for example — nosotros made the release runway name a mandatory field.
If yous take jobs configured without a track name, or without a trackName for Pipeline, you now need to ready the runway name to 'production' to restore the previous behaviour.
For similar reasons, the rollout pct, or rolloutPercentage for Pipeline, must be explicitly specified — it no longer defaults to 100%.
Sorry for whatsoever inconvenience caused by this breaking alter.
Troubleshooting
Error messages from the plugin (many of which come straight from the Google Play API) should more often than not be self-explanatory.
If you're consistently having trouble getting a certain config to work, try uploading the same files manually to Google Play. In that location yous'll likely run across the reason for failure, e.m. a version lawmaking conflict or similar.
Otherwise, please cheque the existing bug reports, and file a new bug report with details, including the build panel log output, if necessary.
Some known error messages and their solutions are shown below:
This means that the Google service account does not accept permission to make the changes that you requested.
Brand sure that you followed the setup instructions above, and confirm that the service account you are using in this Jenkins task has the appropriate permissions in the Google Play Console for the app that you are trying to update.
GoogleJsonResponseException: 500 Internal Server Mistake
Unfortunately, the Google Play API sometimes is not specially reliable, and volition throw generic server errors for no apparent reason.
In these cases y'all can attempt running your build once more, or look a few hours before retrying, if the trouble persists.
Please also consider contacting Google Play Developer Support to aid make them aware that people use the Google Play API, and that it should preferably work in a reliable manner.
Unable to recall an admission token with the provided credentials
If you meet this error message, look further down the error log to encounter what is causing it. Below are a couple of common causes:
Invalid JWT: Token must exist a short-lived token and in a reasonable timeframe
Ensure that the system time is accurate on both the Jenkins controller and build agent, and so endeavor again.
java.cyberspace.SocketTimeoutException: connect timed out
This likely ways your build car is behind an HTTP proxy.
In this case, you should set up Jenkins equally documented on the JenkinsBehindProxy folio.
This plugin just makes secure (HTTPS) requests, so you need to make certain that the -Dhttps.proxyHost=<hostname> and -Dhttps.proxyPort=<port> Java properties are set when starting Jenkins. Add together the advisable http versions of those flags too, if unsecured HTTP requests likewise need to go through the proxy.
Internal error encountered
In some cases, the Google Play API can reply with a very generic error message.
If yous see this, double-check all of your app-related settings on Google Play before trying once more. For example, make sure y'all accept no outstanding bug in your Google Play inbox, Policy Status, App Content, pricing and distribution settings, etc..
Please too contact Google Play Programmer Support to inform them that the Google Play Developers API is returning an unhelpful fault bulletin, and let them know what the crusade was, if y'all manage to resolve the error by updating your Google Play business relationship.
Release rails was non specified; this is now a mandatory parameter
Version 4.0 of the plugin made it mandatory to specify the desired release track name.
If you're seeing this fault, information technology ways yous were relying on the previous behaviour where non specifying a release rail proper noun would default to releasing to the Production runway.
To fix this, update any chore configurations to explicitly set the runway proper name to 'production'.
Rollout percentage was not specified; this is now a mandatory parameter
Version four.0 of the plugin made it mandatory to specify the desired rollout percentage.
If you're seeing this error, it means you were relying on the previous behaviour where non specifying a rollout percentage would default to releasing to 100% of users in the given release track.
To gear up this, update whatever task configurations to explicitly set the rollout percentage to '100'.
Oft asked questions
What if I want to upload APKs with multiple, different application IDs (i.e. build flavours)?
Using the build flavours characteristic of the Android Gradle build arrangement, it'due south possible to have a single Android build which produces multiple APKs, each with a different application ID. e.g. You could have application IDs "com.instance.app" and "com.instance.app.pro" for complimentary and paid versions.
As these may be congenital in a single Jenkins job, people accept wondered why this plugin will refuse to upload APKs with differing application IDs in a single freestyle job.
All the same, equally far every bit Google Play is concerned, these are completely separate apps. This is right and, as such, they should exist uploaded in dissever Jenkins builds: 1 per awarding ID.
If the plugin did allow this and you were to effort to upload, say three, completely different APKs in ane Jenkins build, this would crave opening and committing 3 separate "edit sessions" with the Google Play API. If whatever one of these were to fail — possibly considering of an invalid APK, versionCode conflict, or due to an API failure (which, unfortunately, is non uncommon with the Google Play API) — you would end up with your Google Play account in an inconsistent state. Your Jenkins build would exist marked as failed, merely one or more than applications volition accept actually been uploaded and published to Google Play, and you lot would have to fix the situation manually. Also, yous would not exist able to simply re-run the build, as it would fail due to already-existing APKs.
The all-time do in this case would be to have i chore that builds the different flavours (i.e. the APKs with unlike application IDs) and and then, if the build is successful, it would annal the APKs and start multiple "downstream" Jenkins builds which individually publish each of the applications.
This tin be achieved, for example, with the Parameterized Trigger Plugin and the Copy Artifacts Plugin, i.due east. the "upload" job could be generic, and would receive the APK information via parameter.
Alternatively, if you accept version i.five of this plugin, and apply the Pipeline Plugin, y'all should be able to use the androidApkUpload step multiple times within a single build.
Android apps using this plugin
At that place are several thousand people and companies using this plugin to upload their apps to Google Play, and information technology's always great to hear from people who are using the plugin.
Feel free to let united states of america know via the feedback section below, or open a Pull Request and add yourself and your apps here! :)
Contributing
Y'all can potentially get a sense of what's existence worked on via the tickets on the Jenkins Jira.
Delight contact united states of america (come across below) before working on new features, as we may be working on something already, or at least be able to give advice or pointers.
Feedback
If you accept issues with the plugin that aren't solved via the Troubleshooting section, you can file a bug study with details, including the build panel log output.
Y'all can likewise send us an e-mail with your comments, suggestions, or feedback:
- @orrc
- @jhansche
Changelog
See CHANGELOG.md.
Source: https://plugins.jenkins.io/google-play-android-publisher
0 Response to "How to See Uploads in Google Play Plugin"
Post a Comment