Android: Google Play release
This page tells the owner how to publish the Android app (src/PdfViewer.Android,
application ID io.github.ramanacr.pdfviewer) on Google Play. The repository holds no signing
key and no secret. The owner makes the key on their own computer and gives it to GitHub as
secrets. GitHub builds the signed bundle; the owner uploads it in Play Console by hand.
What the repository does
| Part | What it does |
|---|---|
src/PdfViewer.Android/PdfViewer.Android.csproj |
net10.0-android, so the app targets API level 36. A Release build makes an Android App Bundle (.aab); -p:AndroidPackageFormat=apk makes an APK. |
.github/workflows/android.yml |
On each change: builds an APK signed with a throwaway debug key, checks that there is no permission and that the target is API 36, checks the listing text lengths. Not for a store. It also builds an .aab and checks that it holds the native debug symbols. |
.github/workflows/android-release.yml |
On a tag android-v* or a manual run: builds the signed .aab (for Play) and a signed universal .apk (for a GitHub release), in the protected environment play, with the upload key from secrets. It uploads both as a workflow artifact. It never uploads to Google Play. |
fastlane/metadata/android/en-US/ |
The listing: title, short and full description, release notes, icon, feature graphic, phone screenshots. Google Play and F-Droid read the same files (F-Droid and IzzyOnDroid). |
store/play/ |
Play Console settings and the answers for the Data safety form and the content rating questionnaire. |
Target API level
Google Play requires new apps and app updates to target Android 16 (API level 36) or higher
since 31 August 2026 (Target API level requirements for Google Play apps).
The .NET 9 Android workload stops at API 35; net10.0-android targets API 36 by default
(Target frameworks in SDK-style projects).
So the app now builds with the .NET 10 SDK and its android workload. The workflows install
that workload on the runner.
To build on your own computer, install the workload for SDK 10 once (dotnet workload install
android with the .NET 10 SDK selected). Until you do, -p:AndroidNet9=true builds with the .NET 9
workload (API 35): good for adb install and the emulator, but Play refuses it.
Play also requires native libraries aligned for 16 KB memory pages. In the net10.0-android APK
from this branch’s CI run (and in a local net9.0-android bundle), all 126 native libraries,
SkiaSharp 3.116.1 included, have 16 KB aligned segments. After the first upload, Play Console’s
App bundle explorer shows the same check.
Version numbers
| Value | Where it comes from |
|---|---|
versionName (ApplicationDisplayVersion) |
The tag without android-v: tag android-v0.1 gives 0.1. A manual run takes the version_name input. |
versionCode (ApplicationVersion) |
The version_code input of a manual run, if given (a positive whole number); otherwise the highest N of fastlane/metadata/android/en-US/changelogs/N.txt. |
The run fails if changelogs/<versionCode>.txt does not exist, so a code always has its release
notes. Play refuses a versionCode that it has seen before, and F-Droid and IzzyOnDroid need it to
grow too. So for each release, add the next file (2.txt, 3.txt, …) with its notes, then tag.
Native debug symbols
Play Console warns “This App Bundle contains native code, and you’ve not uploaded debug symbols”
when a bundle has native libraries (.so) and no symbol files for them. Play reads the symbols from
the bundle folder BUNDLE-METADATA/com.android.tools.build.debugsymbols/<abi>/, and uses them to
show function names in native crash reports
(Include native symbols in your release build).
.NET for Android does not fill this folder. It passes each AndroidAppBundleMetaDataFile item to
bundletool as bundle metadata
(.NET for Android build items).
src/PdfViewer.Android/NativeDebugSymbols.targets adds these items to each Release bundle, so
no manual upload is necessary:
Bundle entry (per ABI: arm64-v8a, x86_64) |
Source |
|---|---|
libmonodroid.so.sym |
The .NET for Android runtime host from the runtime pack. It is not stripped (it has a symbol table). |
libxamarin-app.so.dbg |
libxamarin-app.dbg.so, the unstripped copy (with DWARF debug information) that the build keeps of the generated libxamarin-app.so. |
The other native libraries (libmonosgen-2.0.so, libSystem.*.so, libSkiaSharp.so and the AOT
images of the assemblies) come stripped from their NuGet packages, so the build has no symbols
for them. Crashes in them show addresses only. The Android workflow (android.yml) builds a bundle
on each change and fails if one of the four entries is missing; the release workflow checks the
signed bundle too. To see them yourself: unzip -l <bundle>.aab | grep debugsymbols.
If Play still shows the warning after an upload of a bundle with these entries, it is about the stripped libraries above. It is a warning only: it does not block a release.
Deobfuscation file (R8 is off)
Play Console also says “There is no deobfuscation file associated with this App Bundle”. A
deobfuscation file (mapping.txt) exists only when R8 or ProGuard shrinks and renames the
Java/Kotlin code. This app leaves AndroidLinkTool empty, so R8 does not run: the .dex code
keeps its names (it is about 32 KB of generated Java glue for the C# code), and Play’s stack traces
are already readable. The C# code is trimmed by the .NET trimmer (ILLink), which does not rename
anything, so it needs no mapping file either. The warning is information only.
R8 stays off on purpose: it would save almost nothing on 32 KB of .dex, and its keep rules for the
Java glue are a risk of a crash at run time that no CI check would catch. If R8 is turned on later
(<AndroidLinkTool>r8</AndroidLinkTool>), .NET for Android writes mapping.txt and puts it in the
bundle as BUNDLE-METADATA/com.android.tools.build.obfuscation/proguard.map by itself
(AndroidProguardMappingFile),
and the warning goes away.
Steps for the owner
Do these in order. Steps 1 to 3 happen once.
1. Make the upload key on your own computer
Use the keytool of any JDK 17 or later. Keep the file and both passwords in your password
manager and in a safe backup. Never commit the keystore and never paste it in an issue or a
chat.
keytool -genkeypair -v -keystore pdfviewer-upload.keystore -alias upload `
-keyalg RSA -keysize 4096 -validity 10000 `
-dname "CN=Ramana Reddy Chamakura, O=PDF Viewer, C=IN"
keytool asks for the keystore password and the key password (with a PKCS12 keystore, the
default, use the same password for both). Then make the Base64 text for GitHub:
[Convert]::ToBase64String([IO.File]::ReadAllBytes("pdfviewer-upload.keystore")) | Set-Clipboard
2. Make the play environment and its four secrets
- On GitHub: Settings → Environments → New environment, name it
play. - Under Deployment protection rules, tick Required reviewers and add yourself. Under
Deployment branches and tags, choose Selected branches and tags and add the tag rule
android-v*(andmain, for manual runs). -
Under Environment secrets, add:
Secret Value ANDROID_UPLOAD_KEYSTORE_BASE64the Base64 text from step 1 ANDROID_UPLOAD_KEYSTORE_PASSWORDthe keystore password ANDROID_UPLOAD_KEY_ALIASuploadANDROID_UPLOAD_KEY_PASSWORDthe key password
The workflow writes the keystore only to the runner’s temporary folder ($RUNNER_TEMP) and deletes
it in a step that always runs. The passwords reach the build through environment variables
(env: in AndroidSigningStorePass and AndroidSigningKeyPass), never on a command line.
3. Create the app in Play Console and turn on Play App Signing
- Finish the account verification (phone number) in Play Console.
- Create app: name from
fastlane/metadata/android/en-US/title.txt, default language English (United States), App, Free. Accept the declarations. - Play App Signing is on by default for new apps: Google keeps the app signing key, and your key from step 1 is the upload key. Keep the default (“Use a Google-generated key”). You only register your upload key by uploading the first bundle signed with it (step 5).
- Fill in App content and Store listing from
store/play/andfastlane/metadata/android/en-US/: privacy policy URL, ads (none), app access (no restrictions), content rating, target audience, data safety, and the listing text and images.
4. Build the signed bundle
Either push a tag:
git tag android-v0.1
git push origin android-v0.1
or run Actions → Android release (Google Play bundle) → Run workflow with version_name and,
if you want, version_code. Approve the run when GitHub asks (the play environment). When it is
green, download the artifact pdf-viewer-android-<name>-<code>. It holds:
pdf-viewer-<name>-<code>.aab: the bundle for Play.pdf-viewer-<name>-<code>.apk: a universal APK signed with the upload key, for a GitHub release.SHA256SUMS.txt.
The run summary shows the SHA-256 fingerprint of the upload certificate.
5. Upload to Play Console
A new personal developer account must first run a closed test with at least 12 testers who stay opted in for at least 14 days in a row before it can apply for production access (App testing requirements for new personal developer accounts).
- Test and release → Testing → Closed testing → Create track (or use the default “Alpha” track). Add a list of testers (at least 12 Google accounts).
- Create new release, upload the
.aab, paste the release notes fromchangelogs/<versionCode>.txt, review and roll out to the closed track. - Share the opt-in link with the testers. Keep at least 12 of them opted in for 14 days.
- Then, in the Dashboard, Apply for production and answer the questions about the test.
- After approval: Production → Create new release, upload the bundle (or promote the tested release).
For each later release: add changelogs/<next code>.txt, update the description if features changed,
push a new tag (android-v0.2), approve the run, upload the new .aab.
If the upload key is lost or leaked
Because Google holds the app signing key, a lost upload key is not the end of the app: ask for an upload key reset in Play Console → Test and release → App integrity → Play app signing, make a new key as in step 1, and replace the four secrets. The GitHub-release APK would then have a new signature, so IzzyOnDroid would need to be told (see F-Droid and IzzyOnDroid).