Android Signing & Packaging

Android requires every app to be digitally signed before installation, and the signature determines whether future builds are treated as "the same app" and can upgrade installed versions. This guide covers generating a signing key, packaging an APK, and what to watch out for when distributing through Pgyer.

Debug vs. Release Signing

Android Studio automatically uses a debug signature for local builds; for external distribution you need to generate and safeguard a release keystore yourself.

Generating a Keystore

keytool, bundled with the JDK, can produce a long-lived keystore:

keytool -genkeypair -v \
  -keystore my-release-key.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias my-alias

The command prompts for keystore and alias passwords plus organization details — store them in a password manager.

Signature Schemes: V1 / V2 / V3 / V4

Android introduced four signature schemes over time. Newer schemes are backward compatible and don't replace older ones:

Enabling V1 + V2 together (Android Studio's default) covers both older systems and stronger integrity checks.

Packaging with Android Studio

1. Choose Build → Generate Signed Bundle / APK from the menu.
2. Pick APK (not Android App Bundle — see below).
3. Select an existing keystore, or click Create new and fill in alias and passwords.
4. Set Build Variants to release and check both V1 and V2 under Signature Versions.
5. The signed APK ends up in app/release/ inside the module directory.

Packaging with Gradle

Configure signing in app/build.gradle:

android {
    signingConfigs {
        release {
            storeFile file("my-release-key.jks")
            storePassword System.getenv("KEYSTORE_PASSWORD")
            keyAlias "my-alias"
            keyPassword System.getenv("KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

Then run:

./gradlew assembleRelease

The output at app/build/outputs/apk/release/app-release.apk can be uploaded to Pgyer directly.

Verifying an APK's Signature

Before uploading, apksigner from the Android SDK build-tools can verify the signature:

apksigner verify --verbose app-release.apk

The output lists active signature schemes (V1/V2/V3) and certificate details. A DOES NOT VERIFY message means the APK is unsigned or the signature is broken — rebuild.

About Android App Bundle (AAB)

Common Issues

"Signature mismatch" or "conflicting app" error during install Android does not allow apps with the same applicationId but different signatures to overwrite each other. The tester needs to uninstall the old version first. The usual cause: the tester had a debug-signed build installed before receiving a release-signed one.

The download page says "unsigned" after uploading a release APK Run apksigner verify locally first. A DOES NOT VERIFY result usually means the wrong build type was packaged (e.g. debug exported as release) or the signing config didn't take effect.

How should a team share the keystore among multiple packagers? Store the keystore in an encrypted team vault (1Password, Bitwarden) — never in the code repository. In CI, inject the file and passwords via encrypted credentials (GitHub Actions Secret, Jenkins Credentials, etc.) to keep them out of build logs.