fix: remove ephemeral debug keystore signing, require consistent keystore secret

The "Verify and sign APK if needed" step generated a fresh debug keystore
on every CI run. Since GitHub Actions runners are ephemeral, each build
produced a different signing certificate, causing
INSTALL_FAILED_UPDATE_INCOMPATIBLE when trying to update.

Changes:
- release.yml: Remove ephemeral debug keystore fallback, require
  ANDROID_KEYSTORE_BASE64 secret, single signed build path, add
  signature verification step
- generate-keystore.yml: New helper workflow to create a signing
  keystore and provide setup instructions for repository secrets

Agent-Logs-Url: https://github.com/winnerspiros/osu/sessions/df8487e1-1028-44d9-adc9-42e5e885e5a3

Co-authored-by: winnerspiros <1675249+winnerspiros@users.noreply.github.com>

Author: Copilot

.github/workflows/generate-keystore.yml

@@ -0,0 +1,104 @@
+name: Generate Android Signing Keystore
+
+on:
+  workflow_dispatch:
+    inputs:
+      key_password:
+        description: "Password for the keystore and key (min 6 characters)"
+        required: true
+        type: string
+      key_alias:
+        description: "Key alias name"
+        required: false
+        default: "osu-release"
+        type: string
+      validity_days:
+        description: "Certificate validity in days"
+        required: false
+        default: "10000"
+        type: string
+
+jobs:
+  generate:
+    name: Generate Keystore
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate inputs
+        run: |
+          if [ ${#KEY_PASSWORD} -lt 6 ]; then
+            echo "::error::Password must be at least 6 characters."
+            exit 1
+          fi
+        env:
+          KEY_PASSWORD: ${{ inputs.key_password }}
+
+      - name: Generate keystore
+        run: |
+          keytool -genkeypair -v \
+            -keystore osu-release.keystore \
+            -storepass "$KEY_PASSWORD" \
+            -keypass "$KEY_PASSWORD" \
+            -alias "$KEY_ALIAS" \
+            -keyalg RSA -keysize 2048 \
+            -validity "$VALIDITY_DAYS" \
+            -dname "CN=osu! Android Release,O=osu,C=US"
+
+          echo "Keystore generated successfully ✓"
+          keytool -list -v -keystore osu-release.keystore -storepass "$KEY_PASSWORD" | head -20
+        env:
+          KEY_PASSWORD: ${{ inputs.key_password }}
+          KEY_ALIAS: ${{ inputs.key_alias }}
+          VALIDITY_DAYS: ${{ inputs.validity_days }}
+
+      - name: Encode keystore as base64
+        id: encode
+        run: |
+          B64=$(base64 -w 0 osu-release.keystore)
+          # Write to a file for the summary (avoid exposing in logs)
+          echo "$B64" > keystore-base64.txt
+          echo "encoded=true" >> "$GITHUB_OUTPUT"
+
+      - name: Upload keystore artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: osu-signing-keystore
+          path: osu-release.keystore
+          retention-days: 1
+
+      - name: Upload base64 artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: osu-signing-keystore-base64
+          path: keystore-base64.txt
+          retention-days: 1
+
+      - name: Output setup instructions
+        run: |
+          echo ""
+          echo "==================================================================="
+          echo "  KEYSTORE GENERATED — SAVE THESE SECRETS NOW"
+          echo "==================================================================="
+          echo ""
+          echo "  Go to: Settings → Secrets and variables → Actions → New repository secret"
+          echo ""
+          echo "  Add these four secrets:"
+          echo ""
+          echo "  1. ANDROID_KEYSTORE_BASE64"
+          echo "     → Value: contents of the 'keystore-base64.txt' file from the"
+          echo "       'osu-signing-keystore-base64' artifact (download it above)"
+          echo ""
+          echo "  2. ANDROID_SIGNING_KEY_ALIAS"
+          echo "     → Value: ${{ inputs.key_alias }}"
+          echo ""
+          echo "  3. ANDROID_SIGNING_KEY_PASSWORD"
+          echo "     → Value: the password you entered when triggering this workflow"
+          echo ""
+          echo "  4. ANDROID_SIGNING_STORE_PASSWORD"
+          echo "     → Value: the password you entered when triggering this workflow"
+          echo ""
+          echo "  IMPORTANT: Keep a backup of the keystore file! If you lose it,"
+          echo "  you will never be able to update your installed APK — you would"
+          echo "  have to uninstall and reinstall (losing all local data)."
+          echo ""
+          echo "  After saving the secrets, run the 'Build Android APK' workflow."
+          echo "==================================================================="

.github/workflows/release.yml

@@ -78,6 +78,38 @@ jobs:
         env:
           KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
 
+      # Signing is REQUIRED for installable APKs.  Without a consistent keystore
+      # across builds Android will reject updates with INSTALL_FAILED_UPDATE_INCOMPATIBLE.
+      # The old fallback (generating a fresh debug keystore each CI run) produced a
+      # different certificate every time — making every APK incompatible with the last.
+      #
+      # To set up signing, run the "Generate Android Signing Keystore" workflow
+      # (generate-keystore.yml) and save the four secrets it outputs.
+      - name: Require signing keystore
+        if: steps.keystore.outputs.has_keystore != 'true'
+        run: |
+          echo "::error::No signing keystore configured. APK builds require a consistent signing key."
+          echo ""
+          echo "==================================================================="
+          echo "  SETUP INSTRUCTIONS"
+          echo "==================================================================="
+          echo ""
+          echo "  1. Go to Actions → 'Generate Android Signing Keystore' → Run workflow"
+          echo "  2. Download the keystore artifact and copy the base64 from the job summary"
+          echo "  3. Add these four repository secrets (Settings → Secrets → Actions):"
+          echo ""
+          echo "     ANDROID_KEYSTORE_BASE64          = <base64 from step 2>"
+          echo "     ANDROID_SIGNING_KEY_ALIAS        = osu-release"
+          echo "     ANDROID_SIGNING_KEY_PASSWORD     = <password you chose>"
+          echo "     ANDROID_SIGNING_STORE_PASSWORD   = <password you chose>"
+          echo ""
+          echo "  4. Re-run this workflow."
+          echo ""
+          echo "  Why? Each CI run is ephemeral. Without a stored keystore, every build"
+          echo "  gets a different signing certificate, causing INSTALL_FAILED_UPDATE_INCOMPATIBLE."
+          echo "==================================================================="
+          exit 1
+
       - name: Set version
         id: version
         run: |
@@ -88,11 +120,7 @@ jobs:
             echo "version=0.0.0" >> "$GITHUB_OUTPUT"
           fi
 
-      # Always build Release for full optimization (trimming, AOT, compression).
-      # When a keystore is available we sign with it; otherwise the SDK produces
-      # a debug-signed Release APK that can be sideloaded for testing.
-      - name: Build Android APK (signed)
-        if: steps.keystore.outputs.has_keystore == 'true'
+      - name: Build Android APK
         env:
           ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_SIGNING_KEY_ALIAS }}
           ANDROID_KEY_PASS: ${{ secrets.ANDROID_SIGNING_KEY_PASSWORD }}
@@ -111,32 +139,16 @@ jobs:
           -p:AndroidSigningStorePass="$ANDROID_STORE_PASS"
           -p:CustomBeforeMicrosoftCommonTargets="${{ github.workspace }}/build/SuppressSubmoduleWarnings.targets"
 
-      - name: Build Android APK (unsigned Release)
-        if: steps.keystore.outputs.has_keystore != 'true'
-        run: >
-          dotnet publish -c Release
-          osu.Android/osu.Android.csproj
-          -f net10.0-android
-          -p:Version="${{ steps.version.outputs.version }}"
-          -p:ApplicationDisplayVersion="${{ steps.version.outputs.version }}"
-          -p:ApplicationVersion="${{ github.run_number }}"
-          -p:CustomBeforeMicrosoftCommonTargets="${{ github.workspace }}/build/SuppressSubmoduleWarnings.targets"
-
       - name: Find APK
         id: find_apk
         run: |
-          # Both paths build Release.  Signed builds produce *-Signed.apk; unsigned
-          # builds produce the base APK name.  Search publish dir first, then fallback.
-          if [ "${{ steps.keystore.outputs.has_keystore }}" == "true" ]; then
-            APK=$(find "osu.Android/bin/Release/net10.0-android/publish" -maxdepth 1 -name "*-Signed.apk" 2>/dev/null | head -1)
-            if [ -z "$APK" ]; then
-              APK=$(find "osu.Android/bin/Release" -name "*-Signed.apk" | head -1)
-            fi
-          else
+          APK=$(find "osu.Android/bin/Release/net10.0-android/publish" -maxdepth 1 -name "*-Signed.apk" 2>/dev/null | head -1)
+          if [ -z "$APK" ]; then
+            APK=$(find "osu.Android/bin/Release" -name "*-Signed.apk" | head -1)
+          fi
+          if [ -z "$APK" ]; then
+            # Fall back to any APK if -Signed variant isn't produced
             APK=$(find "osu.Android/bin/Release/net10.0-android/publish" -maxdepth 1 -name "*.apk" 2>/dev/null | head -1)
-            if [ -z "$APK" ]; then
-              APK=$(find "osu.Android/bin/Release" -name "*.apk" | head -1)
-            fi
           fi
 
           if [ -z "$APK" ]; then
@@ -150,53 +162,16 @@ jobs:
           echo "Found APK: $APK ($APK_SIZE_MB MB)"
           echo "apk_path=$APK" >> "$GITHUB_OUTPUT"
 
-      # .NET 10 Android SDK may skip debug-signing for Release publish builds.
-      # Verify the APK is signed; if not, sign it with apksigner using the debug
-      # keystore so the APK can be sideloaded without INSTALL_PARSE_FAILED_NO_CERTIFICATES.
-      - name: Verify and sign APK if needed
+      - name: Verify APK signature
         run: |
           APK="${{ steps.find_apk.outputs.apk_path }}"
           APKSIGNER="$ANDROID_HOME/build-tools/$(ls "$ANDROID_HOME/build-tools" | sort -V | tail -1)/apksigner"
-          ZIPALIGN="$ANDROID_HOME/build-tools/$(ls "$ANDROID_HOME/build-tools" | sort -V | tail -1)/zipalign"
 
-          if "$APKSIGNER" verify "$APK" 2>/dev/null; then
-            echo "APK is already signed ✓"
+          if "$APKSIGNER" verify --print-certs "$APK"; then
+            echo "APK signature verified ✓"
           else
-            echo "::warning::APK is not signed. Signing with debug keystore..."
-
-            # Generate debug keystore if it doesn't exist
-            DEBUG_KS="$HOME/.android/debug.keystore"
-            if [ ! -f "$DEBUG_KS" ]; then
-              mkdir -p "$HOME/.android"
-              keytool -genkeypair -v \
-                -keystore "$DEBUG_KS" \
-                -storepass android \
-                -keypass android \
-                -alias androiddebugkey \
-                -keyalg RSA -keysize 2048 -validity 10000 \
-                -dname "CN=Android Debug,O=Android,C=US"
-            fi
-
-            # Zipalign first (required before apksigner v2 signing)
-            ALIGNED_APK="${APK%.apk}-aligned.apk"
-            "$ZIPALIGN" -f -p 4 "$APK" "$ALIGNED_APK"
-            mv "$ALIGNED_APK" "$APK"
-
-            # Sign with debug keystore (v1 + v2 + v3 schemes)
-            "$APKSIGNER" sign \
-              --ks "$DEBUG_KS" \
-              --ks-pass pass:android \
-              --key-pass pass:android \
-              --ks-key-alias androiddebugkey \
-              "$APK"
-
-            # Verify signature
-            if "$APKSIGNER" verify --print-certs "$APK"; then
-              echo "APK signed successfully ✓"
-            else
-              echo "::error::APK signing failed"
-              exit 1
-            fi
+            echo "::error::APK signature verification failed. The APK may not install correctly."
+            exit 1
           fi
 
       - name: Upload APK artifact