[Tauri] Add APK signing (#4685)

haslinghuis · web-flow · commit f9879f4073a9 · 2025-10-29T00:17:10.000+01:00
* Add APK signing

* Fix APK signing: zipalign before signing

The previous implementation had the wrong order:
1. It signed the unsigned APK in-place
2. Then tried to zipalign from the unsigned APK to a signed APK

This caused installation failures with 'You can't install the app on your device'.

The correct order is:
1. Zipalign the unsigned APK to create an aligned APK
2. Sign the aligned APK
3. Move to final signed APK name
4. Verify the signature

Also added signature verification step to catch issues early.

* Set minimum Android SDK to 28 (Android 9.0)

This ensures the APK can only be installed on Android 9.0 (Pie) and beyond.
Previous minSdkVersion was 22 (Android 5.1).

* Set minimum Android SDK to 28 for Tauri (not Capacitor)

Added android.minSdkVersion to tauri.conf.json bundle configuration.
Reverted the Capacitor android/variables.gradle change since that folder
will be replaced by Tauri's generated Android project.

* Android: sign APKs with apksigner (v2/v3), verify; ignore keystores\n\n- Zipalign before signing\n- Use apksigner to produce modern signatures (fixes install failures)\n- Verify with apksigner verify\n- Remove committed debug.keystore and ignore keystore files

* Use secrets context directly
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
@@ -157,18 +157,74 @@ 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"
+          ALIGNED_APK="${UNSIGNED_APK%-unsigned.apk}-aligned.apk"
+          
+          # First zipalign the unsigned APK
+          echo "Zipaligning APK..."
+          ${ANDROID_HOME}/build-tools/$(ls ${ANDROID_HOME}/build-tools | tail -1)/zipalign -v -p 4 "$UNSIGNED_APK" "$ALIGNED_APK"
+
+          # Then sign the aligned APK with v2/v3 signature using apksigner
+          echo "Signing APK to: $SIGNED_APK"
+          BUILD_TOOLS_VERSION=$(ls ${ANDROID_HOME}/build-tools | tail -1)
+          ${ANDROID_HOME}/build-tools/${BUILD_TOOLS_VERSION}/apksigner sign \
+            --ks "${HOME}/.android/debug.keystore" \
+            --ks-key-alias androiddebugkey \
+            --ks-pass pass:android \
+            --key-pass pass:android \
+            --v1-signing-enabled true \
+            --out "$SIGNED_APK" \
+            "$ALIGNED_APK"
+
+          echo "Signed APK created: $SIGNED_APK"
+          ls -lh "$SIGNED_APK"
+
+          # Verify the signature
+          ${ANDROID_HOME}/build-tools/${BUILD_TOOLS_VERSION}/apksigner verify --verbose --print-certs "$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
@@ -99,13 +99,114 @@ jobs:
         run: |
           yarn android:release
 
+      - name: Setup release keystore (if available)
+        if: ${{ secrets.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"
+            ALIGNED_APK="${UNSIGNED_APK%-unsigned.apk}-aligned.apk"
+            
+            # First zipalign the unsigned APK
+            echo "Zipaligning APK..."
+            BUILD_TOOLS_VERSION=$(ls ${ANDROID_HOME}/build-tools | tail -1)
+            ${ANDROID_HOME}/build-tools/${BUILD_TOOLS_VERSION}/zipalign -v -p 4 "$UNSIGNED_APK" "$ALIGNED_APK"
+
+            # Then sign the aligned APK with v2/v3 signatures using apksigner
+            echo "Signing aligned APK..."
+            ${ANDROID_HOME}/build-tools/${BUILD_TOOLS_VERSION}/apksigner sign \
+              --ks "$KEYSTORE" \
+              --ks-key-alias "$KEY_ALIAS" \
+              --ks-pass pass:"$STORE_PASS" \
+              --key-pass pass:"$KEY_PASS" \
+              --v1-signing-enabled true \
+              --out "$SIGNED_APK" \
+              "$ALIGNED_APK"
+            echo "Signed APK created: $SIGNED_APK"
+            ls -lh "$SIGNED_APK"
+            
+            # Verify the signature
+            ${ANDROID_HOME}/build-tools/${BUILD_TOOLS_VERSION}/apksigner verify --verbose --print-certs "$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: |
-            android/app/build/outputs/apk/release/*.apk
-            android/app/build/outputs/bundle/release/*.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/.gitignore b/.gitignore
@@ -51,3 +51,8 @@ build
 # Ignore Tauri build artifacts
 src-tauri/target/
 src-tauri/gen/
+
+# Keystores (never commit signing keys)
+*.keystore
+*.jks
+debug.keystore
diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json
@@ -28,7 +28,10 @@
   "bundle": {
     "active": true,
     "targets": ["deb", "appimage", "dmg", "nsis"],
-    "icon": ["icons/bf_icon_128.png"]
+    "icon": ["icons/bf_icon_128.png"],
+    "android": {
+      "minSdkVersion": 28
+    }
   },
   "plugins": {
     "shell": {
