Add APK signing

haslinghuis · haslinghuis · commit 50fc73308616 · 2025-10-28T17:37:17.000+01:00
diff --git a/.github/ANDROID_SIGNING.md b/.github/ANDROID_SIGNING.md
@@ -0,0 +1,119 @@
+# Android APK Signing Guide
+
+## Overview
+
+Android requires all APKs to be signed before they can be installed on devices. This repository supports both **debug signing** (for development/testing) and **release signing** (for production releases).
+
+## CI/PR Builds (Debug Signing)
+
+PR builds in the `ci.yml` workflow automatically sign APKs with a **debug keystore**. These are suitable for:
+- Testing on development devices
+- Internal QA
+- Feature validation
+
+The debug-signed APKs can be downloaded from the PR's workflow artifacts and installed on any Android device with developer mode enabled.
+
+## Release Builds (Production Signing)
+
+For production releases via the `release.yml` workflow, you should configure a **release keystore** using GitHub Secrets.
+
+### Creating a Release Keystore
+
+If you don't already have a release keystore, create one:
+
+```bash
+keytool -genkeypair -v \
+  -keystore betaflight-release.keystore \
+  -storepass <YOUR_STORE_PASSWORD> \
+  -alias betaflight \
+  -keypass <YOUR_KEY_PASSWORD> \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000 \
+  -dname "CN=Betaflight,O=Betaflight,C=US"
+```
+
+**⚠️ IMPORTANT**: Keep this keystore file and passwords secure. If you lose them, you cannot update your app on the Play Store!
+
+### Configure GitHub Secrets
+
+Add the following secrets to your GitHub repository (Settings → Secrets and variables → Actions):
+
+1. **ANDROID_KEYSTORE_BASE64**
+   ```bash
+   base64 -w 0 betaflight-release.keystore
+   ```
+   Copy the output and paste it as the secret value.
+
+2. **ANDROID_KEYSTORE_PASSWORD**  
+   The password you used for `-storepass` when creating the keystore.
+
+3. **ANDROID_KEY_ALIAS**  
+   The alias you used (e.g., `betaflight`).
+
+4. **ANDROID_KEY_PASSWORD**  
+   The password you used for `-keypass` when creating the keystore.
+
+### How Release Signing Works
+
+When you trigger a release build:
+
+1. If **all four secrets are configured**, the workflow will:
+   - Decode the base64 keystore
+   - Sign both the APK and AAB with your release key
+   - Upload signed artifacts with `-release-signed` suffix
+
+2. If **secrets are NOT configured**, the workflow will:
+   - Fall back to debug signing
+   - Upload APKs with `-debug-signed` suffix
+   - ⚠️ These cannot be uploaded to the Play Store!
+
+## Verifying Signed APKs
+
+To verify an APK signature:
+
+```bash
+# Check signature
+jarsigner -verify -verbose -certs your-app.apk
+
+# View certificate details
+keytool -printcert -jarfile your-app.apk
+```
+
+For release APKs, the certificate should match your release keystore.  
+For debug APKs, the certificate will show "CN=Android Debug".
+
+## Installing Signed APKs
+
+### Debug-signed APKs
+- Enable "Install from unknown sources" or "Install unknown apps" on your Android device
+- Download the APK from GitHub Actions artifacts
+- Install via file manager or `adb install path/to/app.apk`
+
+### Release-signed APKs
+- Can be installed the same way as debug APKs
+- Can be uploaded to Google Play Store for distribution
+- Must be signed with the same keystore for app updates
+
+## Security Best Practices
+
+1. **Never commit keystores to the repository**
+2. **Keep keystore passwords in GitHub Secrets only**
+3. **Back up your release keystore securely** (preferably in multiple secure locations)
+4. **Use strong passwords** for both keystore and key alias
+5. **Limit access** to GitHub Secrets to trusted maintainers only
+
+## Troubleshooting
+
+### "APK not signed" error during installation
+- The APK must be signed (either debug or release)
+- Check workflow logs to ensure signing step completed successfully
+
+### "App not installed" or "Package conflicts" error
+- You may have an existing version signed with a different key
+- Uninstall the old version first, then install the new APK
+
+### Release workflow falls back to debug signing
+- Check that all four GitHub Secrets are configured correctly
+- Verify the base64-encoded keystore is valid: `echo "$SECRET" | base64 -d > test.keystore`
+- Check workflow logs for any error messages in the "Setup release keystore" step
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -169,18 +169,62 @@ jobs:
           tauriScript: yarn tauri android
           includeUpdaterJson: false
 
+      - name: Generate debug keystore
+        shell: bash
+        run: |
+          set -euo pipefail
+          KEYSTORE_PATH="${HOME}/.android/debug.keystore"
+          mkdir -p "${HOME}/.android"
+          if [ ! -f "$KEYSTORE_PATH" ]; then
+            echo "Generating debug keystore at $KEYSTORE_PATH"
+            keytool -genkeypair -v \
+              -keystore "$KEYSTORE_PATH" \
+              -storepass android \
+              -alias androiddebugkey \
+              -keypass android \
+              -keyalg RSA \
+              -keysize 2048 \
+              -validity 10000 \
+              -dname "CN=Android Debug,O=Android,C=US"
+          else
+            echo "Debug keystore already exists at $KEYSTORE_PATH"
+          fi
+
+      - name: Sign APK with debug key
+        shell: bash
+        run: |
+          set -euo pipefail
+          UNSIGNED_APK=$(find src-tauri/gen/android/app/build/outputs/apk -name "*-unsigned.apk" | head -1)
+          if [ -z "$UNSIGNED_APK" ]; then
+            echo "Error: No unsigned APK found"
+            exit 1
+          fi
+          echo "Found unsigned APK: $UNSIGNED_APK"
+          SIGNED_APK="${UNSIGNED_APK%-unsigned.apk}-debug-signed.apk"
+          echo "Signing APK to: $SIGNED_APK"
+          jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 \
+            -keystore "${HOME}/.android/debug.keystore" \
+            -storepass android \
+            -keypass android \
+            "$UNSIGNED_APK" \
+            androiddebugkey
+          # Zipalign the signed APK
+          ${ANDROID_HOME}/build-tools/$(ls ${ANDROID_HOME}/build-tools | tail -1)/zipalign -v 4 "$UNSIGNED_APK" "$SIGNED_APK"
+          echo "Signed APK created: $SIGNED_APK"
+          ls -lh "$SIGNED_APK"
+
       - name: Inspect Android bundle output
         if: always()
         run: |
           echo "Android APK artifacts:"
           find src-tauri/gen/android -type f -name "*.apk" -print || true
 
-      - name: Upload Android APK
+      - name: Upload signed Android APK
         uses: actions/upload-artifact@v4
         with:
-          name: android-apk
+          name: android-apk-debug-signed
           path: |
-            src-tauri/gen/android/app/build/outputs/apk/**/*.apk
+            src-tauri/gen/android/app/build/outputs/apk/**/*-debug-signed.apk
           if-no-files-found: warn
           retention-days: 14
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -124,13 +124,103 @@ jobs:
         run: |
           yarn tauri:build:android
 
+      - name: Setup release keystore (if available)
+        if: ${{ env.ANDROID_KEYSTORE_BASE64 != '' }}
+        env:
+          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          echo "Setting up release keystore from secrets"
+          echo "$ANDROID_KEYSTORE_BASE64" | base64 -d > release.keystore
+          echo "KEYSTORE_PATH=$(pwd)/release.keystore" >> $GITHUB_ENV
+          echo "KEYSTORE_PASSWORD=$ANDROID_KEYSTORE_PASSWORD" >> $GITHUB_ENV
+          echo "KEY_ALIAS=$ANDROID_KEY_ALIAS" >> $GITHUB_ENV
+          echo "KEY_PASSWORD=$ANDROID_KEY_PASSWORD" >> $GITHUB_ENV
+
+      - name: Sign APK/AAB (release or debug)
+        shell: bash
+        run: |
+          set -euo pipefail
+          
+          # Determine signing configuration
+          if [ -f "release.keystore" ]; then
+            echo "Using release keystore for signing"
+            KEYSTORE="release.keystore"
+            STORE_PASS="${KEYSTORE_PASSWORD}"
+            KEY_ALIAS="${KEY_ALIAS}"
+            KEY_PASS="${KEY_PASSWORD}"
+            SUFFIX="release-signed"
+          else
+            echo "No release keystore found - using debug keystore"
+            mkdir -p "${HOME}/.android"
+            KEYSTORE="${HOME}/.android/debug.keystore"
+            if [ ! -f "$KEYSTORE" ]; then
+              echo "Generating debug keystore"
+              keytool -genkeypair -v \
+                -keystore "$KEYSTORE" \
+                -storepass android \
+                -alias androiddebugkey \
+                -keypass android \
+                -keyalg RSA \
+                -keysize 2048 \
+                -validity 10000 \
+                -dname "CN=Android Debug,O=Android,C=US"
+            fi
+            STORE_PASS="android"
+            KEY_ALIAS="androiddebugkey"
+            KEY_PASS="android"
+            SUFFIX="debug-signed"
+          fi
+          
+          # Sign APK
+          UNSIGNED_APK=$(find src-tauri/gen/android/app/build/outputs/apk -name "*-unsigned.apk" | head -1)
+          if [ -n "$UNSIGNED_APK" ]; then
+            echo "Signing APK: $UNSIGNED_APK"
+            SIGNED_APK="${UNSIGNED_APK%-unsigned.apk}-${SUFFIX}.apk"
+            jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 \
+              -keystore "$KEYSTORE" \
+              -storepass "$STORE_PASS" \
+              -keypass "$KEY_PASS" \
+              "$UNSIGNED_APK" \
+              "$KEY_ALIAS"
+            # Zipalign
+            BUILD_TOOLS_VERSION=$(ls ${ANDROID_HOME}/build-tools | tail -1)
+            ${ANDROID_HOME}/build-tools/${BUILD_TOOLS_VERSION}/zipalign -f -v 4 "$UNSIGNED_APK" "$SIGNED_APK"
+            echo "Signed APK created: $SIGNED_APK"
+            ls -lh "$SIGNED_APK"
+          else
+            echo "Warning: No unsigned APK found"
+          fi
+          
+          # Sign AAB (if release keystore available)
+          if [ -f "release.keystore" ]; then
+            UNSIGNED_AAB=$(find src-tauri/gen/android/app/build/outputs/bundle -name "*.aab" | head -1)
+            if [ -n "$UNSIGNED_AAB" ]; then
+              echo "Signing AAB: $UNSIGNED_AAB"
+              SIGNED_AAB="${UNSIGNED_AAB%.aab}-signed.aab"
+              jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 \
+                -keystore "$KEYSTORE" \
+                -storepass "$STORE_PASS" \
+                -keypass "$KEY_PASS" \
+                "$UNSIGNED_AAB" \
+                "$KEY_ALIAS"
+              mv "$UNSIGNED_AAB" "$SIGNED_AAB"
+              echo "Signed AAB created: $SIGNED_AAB"
+              ls -lh "$SIGNED_AAB"
+            fi
+          fi
+
       - name: Upload APK/AAB artifacts
         uses: actions/upload-artifact@v4
         with:
           name: betaflight-android
           path: |
-            src-tauri/gen/android/app/build/outputs/apk/universal/release/*.apk
-            src-tauri/gen/android/app/build/outputs/bundle/universalRelease/*.aab
+            src-tauri/gen/android/app/build/outputs/apk/universal/release/*-signed.apk
+            src-tauri/gen/android/app/build/outputs/bundle/universalRelease/*-signed.aab
           if-no-files-found: warn
           retention-days: 30
 
diff --git a/debug.keystore b/debug.keystore
