How do you sign a React Native Android release with your own upload keystore instead of the template's debug keystore?

## Where a fresh project starts A new React Native app's `android/app/build.gradle` defines only one signing config, `debug`, pointing at the `debug.keystore` that ships in `android/app` with the well-known password `android`. Its `release` build type reuses it: ```groovy buildTypes { release { // Caution! In production, you need to generate your own keystore file. signingConfig signingConfigs.debug minifyEnabled enableProguardInReleaseBuilds } } ``` That makes `--mode release` work out of the box on a laptop, but the result is signed with a public debug key, which Google Play does not accept. Before a first Play release you replace it with your own **upload key**. ## The steps, as the React Native docs describe them 1. **Generate the keystore.** `keytool -genkeypair -v -storetype PKCS12 -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000` asks for passwords and a distinguished name, and writes one key valid for 10,000 days. 2. **Place it** in `android/app`, next to the debug keystore. 3. **Declare four Gradle properties**, preferably in `~/.gradle/gradle.properties` so they never reach the repository: ```properties MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore MYAPP_UPLOAD_KEY_ALIAS=my-key-alias MYAPP_UPLOAD_STORE_PASSWORD=***** MYAPP_UPLOAD_KEY_PASSWORD=***** ``` 4. **Add a release signing config and use it:** ```groovy signingConfigs { release { if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) { storeFile file(MYAPP_UPLOAD_STORE_FILE) storePassword MYAPP_UPLOAD_STORE_PASSWORD keyAlias MYAPP_UPLOAD_KEY_ALIAS keyPassword MYAPP_UPLOAD_KEY_PASSWORD } } } buildTypes { release { signingConfig signingConfigs.release } } ``` 5. **Build** with `npx react-native build-android --mode=release` and upload the AAB. The `MYAPP_` prefix is only a naming convention from the docs; Gradle treats them as ordinary project properties. ## Upload key vs app signing key With **Play App Signing**, which any app published as an AAB uses, there are two keys: | Key | Who holds it | What it signs | If lost | |---|---|---|---| | Upload key | You | Each AAB you upload | The account owner can request a reset | | App signing key | Google Play | The APKs installed on devices | Held by Google, not your problem to back up | The upload key proves to Play that an upload came from you. Play then signs the device APKs with the app signing key. That split is what makes a lost upload key recoverable. ## The `hasProperty` guard and other details - **The guard lets the project configure without secrets.** A teammate without the properties can still sync and run debug builds, but a release they build is not signed with the upload key. Check which key signed an artifact before uploading it. - **Plaintext passwords.** The docs suggest macOS Keychain as an alternative to storing the two passwords in `gradle.properties`. - **Never commit the keystore or passwords.** Back the keystore up somewhere durable, together with its alias and passwords, and record who has access. - **Certificate fingerprints change.** Because devices receive APKs signed by the app signing key, any service that allowlists your app by certificate fingerprint needs that key's fingerprint from the Play Console, not only your upload key's. ## Checking what you are about to upload Before the first upload it is worth confirming the artifact is signed by the upload key and not the debug key: - The JDK's `keytool -printcert -jarfile app-release.aab` prints the certificate that signed the bundle; compare its fingerprint with `keytool -list -v` on your upload keystore. - A certificate that matches the template's `debug.keystore` means the release build type still points at `signingConfigs.debug`, or the `MYAPP_UPLOAD_*` properties were missing on that machine. - Test the signed release on a device with `npm run android -- --mode="release"` before uploading, so signing and bundling problems surface locally. ## The scenario: the first Play release of a language-learning app The team has been testing with `--mode release` for weeks, so everything looks ready. The first upload bounces because the AAB is debug-signed. They generate an upload keystore, add the properties on the release machine, wire `signingConfigs.release` and rebuild. The upload is accepted and Play enrols the app in Play App Signing. Later, sign-in through a provider that checks the app's certificate fingerprint fails only in the Play-installed build; the fix is to register the app signing key's fingerprint as well.