Use a fixed release keystore for Android signing (CI signs with ephemeral debug keys)

[TMaYaD]

User Story

As a Jeeves release engineer, I want every Android artifact we ship — Firebase App Distribution drops, GitHub Releases APK/AAB, and any future Play Store / Solana dApp Store upload — to be signed with a stable, project-owned release key, so that upgrades install over previous builds, the Play upload key never rotates underneath us, and we stop relying on an ephemeral debug key generated fresh on every CI runner.

Problem

app/android/app/build.gradle.kts:44-50 currently signs the release build type with the debug signing config:

buildTypes {
    release {
        // TODO: Add your own signing config for the release build.
        // Signing with the debug keys for now, so `flutter run --release` works.
        signingConfig = signingConfigs.getByName("debug")
    }
}

None of the workflows (.github/workflows/flutter-ci.yml, pr-apk.yml, cd-app.yml) install a stored keystore or load any signing secret. The Android SDK auto-generates ~/.android/debug.keystore on first use, so each GitHub Actions runner ends up with its own ephemeral debug key.

Concrete consequences:

• Per-PR APKs distributed via Firebase App Distribution (pr-apk.yml:97-103) cannot be installed over a previous build from a different runner without uninstall-first.
• The production release APK + AAB built by cd-app.yml:259-267 and uploaded to GitHub Releases / Firebase App Distribution are debug-signed, with a different key per run.
• The Seeker APK (cd-app.yml:342-349) destined for the Solana dApp Store has the same problem.
• The AAB cannot be uploaded to Google Play — debug keys are rejected for upload, and even if they weren't, the key would change on every run.

Scope

• Generate a project-owned release keystore (and a separate upload keystore for Play if/when we publish there — Play App Signing then handles the distribution key).
• Store the keystore + credentials as GitHub Actions secrets:
  • ANDROID_KEYSTORE_BASE64 (the .jks file, base64-encoded)
  • ANDROID_KEYSTORE_PASSWORD
  • ANDROID_KEY_ALIAS
  • ANDROID_KEY_PASSWORD
• In app/android/, read credentials from key.properties (gitignored) and a real signingConfigs.release { ... } block; wire buildTypes.release.signingConfig = signingConfigs.getByName("release") in app/android/app/build.gradle.kts.
• Allow local flutter run --release to keep working when key.properties is absent — fall back to debug signing only in that case, never on CI.
• In CI:
  • cd-app.yml (build-android, build-seeker): decode the secret into app/android/keystore.jks, write key.properties, then build.
  • pr-apk.yml: same setup so tester upgrades work seamlessly (the dev flavor APK should also be signed with a stable key — separate dev key alias if we want it isolated from prod).
  • flutter-ci.yml android-build job stays debug-signed (smoke test only).
• Document the rotation process and the secret list in docs/RELEASES.md.
• Add a CI guard that fails the prod build if key.properties was not produced (i.e. secrets missing) — silent fall-back to debug on prod is the failure mode we're fixing.

Acceptance Criteria

• app/android/app/build.gradle.kts defines a signingConfigs.release block backed by key.properties, and buildTypes.release uses it.
• cd-app.yml produces a release APK + AAB signed with the project's release key; apksigner verify --print-certs shows the same SHA-256 fingerprint across two consecutive runs.
• The Seeker variant (build-seeker) is signed with the same release key.
• pr-apk.yml produces APKs signed with a stable key (dev or release); a tester can install build N+1 over build N without uninstalling.
• Local flutter run --release still works on a developer machine without key.properties (debug fallback only when key.properties is missing).
• Prod CD fails fast with a clear error if signing secrets are not configured — no silent debug-signing on the published artifacts.
• docs/RELEASES.md documents the keystore, the GitHub Actions secrets, and the rotation procedure.
• key.properties and *.jks are gitignored.

Out of Scope

• Enabling Play App Signing or actually publishing to the Google Play Store (separate issue when we're ready to ship to Play).
• Submitting to the Solana dApp Store (separate issue; this one just ensures the Seeker APK is signed with a stable key when we get there).
• iOS code signing (see iOS support: run Jeeves natively on iPhone/iPad #123).

Related

• Automate per-PR Flutter APK builds and distribute to testers via Firebase App Distribution #147 — per-PR Firebase App Distribution (explicitly listed signed Play builds as out of scope).
• app/android/app/build.gradle.kts:44-50 — current TODO.
• .github/workflows/cd-app.yml, .github/workflows/pr-apk.yml, .github/workflows/flutter-ci.yml.

[trixy-the-ai-bot]

I have enough context. Here's the plan.

---

Implementation Plan — Issue #300: Fixed Release Keystore for Android Signing

Goal

Replace the ephemeral debug-key signing of release builds with a stable, project-owned release keystore. The same key must sign every distributable Android artifact (PR Firebase APKs, production APK + AAB, Seeker APK) across CI runs so installs upgrade in place and Play Store upload becomes feasible.

Design Decisions

Two keys, not one

• release key — signs production-flavor APK + AAB + Seeker APK. This is the key end users get.
• dev key — signs dev-flavor APKs distributed via pr-apk.yml. Separate so:
  • A leaked dev key (more exposure: every PR build) doesn't endanger prod.
  • Dev and prod flavors have different applicationIds already (loonyb.in.jeeves.dev vs loonyb.in.jeeves) so they install side-by-side; using separate keys is purely about blast radius.

Both keystores live as separate GitHub Actions secrets. The Gradle config picks the right one based on the flavor.

Secret design

GitHub Actions secrets:

Secret	Purpose
ANDROID_RELEASE_KEYSTORE_BASE64	base64-encoded .jks for production-flavor release signing
ANDROID_RELEASE_KEYSTORE_PASSWORD	store password
ANDROID_RELEASE_KEY_ALIAS	key alias inside the store
ANDROID_RELEASE_KEY_PASSWORD	key password
ANDROID_DEV_KEYSTORE_BASE64	base64-encoded .jks for dev-flavor PR builds
ANDROID_DEV_KEYSTORE_PASSWORD	dev store password
ANDROID_DEV_KEY_ALIAS	dev key alias
ANDROID_DEV_KEY_PASSWORD	dev key password

(Naming kept distinct from the issue's ANDROID_KEYSTORE_* proposal so the dev/prod split is explicit and there's no ambiguity which one CI is loading.)

key.properties layout

A single gitignored file at app/android/key.properties with optional sections for each flavor:

releaseStoreFile=keystore-release.jks
releaseStorePassword=...
releaseKeyAlias=...
releaseKeyPassword=...

devStoreFile=keystore-dev.jks
devStorePassword=...
devKeyAlias=...
devKeyPassword=...

Gradle reads this once and exposes both signing configs. Either block may be absent (e.g. a developer who only cares about prod release builds locally).

Local-dev fallback

If key.properties is missing or the relevant block is missing, signingConfigs.<flavor>Release resolves to signingConfigs.getByName("debug") so flutter run --release still works. The CI guard (below) prevents this fallback from being silently used on the prod CD path.

File-by-file changes

1. app/android/app/build.gradle.kts

• Top of file: load key.properties if present:

  import java.util.Properties
  import java.io.FileInputStream
  
  val keystoreProperties = Properties().apply {
      val f = rootProject.file("key.properties")
      if (f.exists()) FileInputStream(f).use { load(it) }
  }
  fun keystoreProperties.has(key: String) = getProperty(key)?.isNotBlank() == true

• Inside android { ... }, add a signingConfigs { ... } block:

  signingConfigs {
      if (keystoreProperties.has("releaseStoreFile")) {
          create("release") {
              storeFile = rootProject.file(keystoreProperties.getProperty("releaseStoreFile"))
              storePassword = keystoreProperties.getProperty("releaseStorePassword")
              keyAlias = keystoreProperties.getProperty("releaseKeyAlias")
              keyPassword = keystoreProperties.getProperty("releaseKeyPassword")
          }
      }
      if (keystoreProperties.has("devStoreFile")) {
          create("devRelease") {
              storeFile = rootProject.file(keystoreProperties.getProperty("devStoreFile"))
              storePassword = keystoreProperties.getProperty("devStorePassword")
              keyAlias = keystoreProperties.getProperty("devKeyAlias")
              keyPassword = keystoreProperties.getProperty("devKeyPassword")
          }
      }
  }

• Rewrite buildTypes.release — drop the debug-only path. Per-flavor wiring happens via a productFlavors matchup:

  productFlavors {
      create("production") {
          dimension = "environment"
          signingConfig = signingConfigs.findByName("release") ?: signingConfigs.getByName("debug")
      }
      create("dev") {
          dimension = "environment"
          applicationIdSuffix = ".dev"
          resValue("string", "app_name", "Jeeves dev")
          signingConfig = signingConfigs.findByName("devRelease") ?: signingConfigs.getByName("debug")
      }
  }
  
  buildTypes {
      release {
          // signingConfig is picked from the productFlavor (release/devRelease)
          // and falls back to debug if key.properties is absent — see signingConfigs above.
      }
  }

  Verify the per-flavor signingConfig overrides the buildType-level config the way AGP expects (it does — flavor-level wins). If it doesn't behave cleanly, fall back to setting the buildType signingConfig via a Gradle expression that selects based on the active flavor (less clean but workable).
• Remove the obsolete // TODO: Add your own signing config… comment.

2. app/android/.gitignore

Already covers key.properties, **/*.keystore, **/*.jks — no change needed. Verify and stop.

3. New shared GitHub Actions composite action

Create .github/actions/setup-android-signing/action.yml to avoid duplicating the keystore-decode logic across three workflows:

name: Set up Android signing
description: Decodes base64 keystores and writes app/android/key.properties.
inputs:
  release-keystore-base64:
    required: false
  release-keystore-password:
    required: false
  release-key-alias:
    required: false
  release-key-password:
    required: false
  dev-keystore-base64:
    required: false
  dev-keystore-password:
    required: false
  dev-key-alias:
    required: false
  dev-key-password:
    required: false
  require-release:
    description: Fail if release keystore inputs are missing.
    default: 'false'
runs:
  using: composite
  steps:
    - shell: bash
      working-directory: app/android
      run: |
        set -euo pipefail

        wrote_any=false
        : > key.properties

        if [ -n "${{ inputs.release-keystore-base64 }}" ]; then
          echo "${{ inputs.release-keystore-base64 }}" | base64 -d > keystore-release.jks
          {
            echo "releaseStoreFile=keystore-release.jks"
            echo "releaseStorePassword=${{ inputs.release-keystore-password }}"
            echo "releaseKeyAlias=${{ inputs.release-key-alias }}"
            echo "releaseKeyPassword=${{ inputs.release-key-password }}"
          } >> key.properties
          wrote_any=true
        elif [ "${{ inputs.require-release }}" = "true" ]; then
          echo "::error::ANDROID_RELEASE_KEYSTORE_BASE64 is not configured; cannot sign release artifacts."
          exit 1
        fi

        if [ -n "${{ inputs.dev-keystore-base64 }}" ]; then
          echo "${{ inputs.dev-keystore-base64 }}" | base64 -d > keystore-dev.jks
          {
            echo "devStoreFile=keystore-dev.jks"
            echo "devStorePassword=${{ inputs.dev-keystore-password }}"
            echo "devKeyAlias=${{ inputs.dev-key-alias }}"
            echo "devKeyPassword=${{ inputs.dev-key-password }}"
          } >> key.properties
          wrote_any=true
        fi

        if [ "$wrote_any" = "false" ]; then rm -f key.properties; fi

The require-release: true input is the CI guard: prod CD passes it so a missing secret fails fast instead of silently falling back to debug-signing.

4. .github/workflows/cd-app.yml

In both build-android and build-seeker jobs, insert the setup step before flutter build:

- uses: ./.github/actions/setup-android-signing
  with:
    release-keystore-base64: ${{ secrets.ANDROID_RELEASE_KEYSTORE_BASE64 }}
    release-keystore-password: ${{ secrets.ANDROID_RELEASE_KEYSTORE_PASSWORD }}
    release-key-alias: ${{ secrets.ANDROID_RELEASE_KEY_ALIAS }}
    release-key-password: ${{ secrets.ANDROID_RELEASE_KEY_PASSWORD }}
    require-release: 'true'

Add a post-build verification step in build-android (best-effort, doesn't fail if apksigner not on PATH — it ships with the Android SDK that flutter installs):

- name: Verify APK is signed with the release key
  run: |
    APKSIGNER=$(find "$ANDROID_HOME/build-tools" -name apksigner | sort -V | tail -1)
    "$APKSIGNER" verify --print-certs build/app/outputs/flutter-apk/app-production-release.apk

5. .github/workflows/pr-apk.yml

Insert before flutter build apk --profile --flavor dev:

- uses: ./.github/actions/setup-android-signing
  with:
    dev-keystore-base64: ${{ secrets.ANDROID_DEV_KEYSTORE_BASE64 }}
    dev-keystore-password: ${{ secrets.ANDROID_DEV_KEYSTORE_PASSWORD }}
    dev-key-alias: ${{ secrets.ANDROID_DEV_KEY_ALIAS }}
    dev-key-password: ${{ secrets.ANDROID_DEV_KEY_PASSWORD }}

No require-release: true here — dev PRs don't gate on prod secrets being present, but they will silently use debug-signing if the dev secret is missing (acceptable for PR builds; we should log a warning in the action when neither key was loaded).

Note: the current pr-apk.yml builds --profile not --release. --profile uses the profile buildType (which inherits from debug). Decide:

• Option A (recommended): keep --profile but configure buildTypes.profile { signingConfig = ... } the same way release is configured. Mirrors current behavior, just stably signed.
• Option B: switch to --release --flavor dev so the same code path that ships to users is the one testers see. Bigger behavioral change; out of scope for this issue.

Go with A. Update the Gradle config to apply the same per-flavor signingConfig logic to the profile build type, not just release. Question for the user: confirm A vs. B before implementing.

6. .github/workflows/flutter-ci.yml

android-build is a smoke test that runs flutter build apk --debug. Debug builds are signed with the Android-SDK-managed ~/.android/debug.keystore regardless of signingConfigs. No change needed. Add a one-line comment in the workflow explaining why this job intentionally skips the signing setup, so a future reader doesn't add it speculatively.

7. docs/RELEASES.md

Add a new top-level section "Android signing" between the existing "Firebase App Distribution channels" and "Not yet wired" sections. Cover:

• Why two keys. Release key signs prod artifacts users install; dev key signs PR/dev-flavor builds. Separating limits blast radius if dev key leaks.
• The eight secrets listed by name in a table, with which workflow consumes each.
• Where the keystores live. Local backup paths (1Password vault or equivalent — confirm with user where the team stores secrets today).
• Generation procedure. Exact keytool -genkeypair invocation, recommended validity (25+ years for the release key — Play requires keys valid past 2033), and how to base64-encode for the GitHub secret (base64 -w0 keystore-release.jks).
• Rotation procedure. Out-of-process step-by-step: (1) generate new key; (2) update all four *_RELEASE_* secrets in GitHub; (3) bump versionCode and ship a release; (4) testers must uninstall and reinstall once because signature changed. Note that this is one-way pain — once we adopt Play App Signing, the upload key can rotate without forcing reinstalls.
• Verifying a build is signed correctly. apksigner verify --print-certs <apk> and the SHA-256 fingerprint of the canonical release key (record it in the doc once the key is generated).

Remove the "Not yet wired" entry about Play Store upload still being signed with an unstable key (replace with the narrower remaining gap: configuring Play Console + Play App Signing, which is genuinely separate work).

8. Out-of-process steps for the user

Claude cannot generate the keystore or set GitHub secrets directly. Provide the user with:

1. keytool -genkeypair -v -keystore keystore-release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias jeeves-release (and similar for dev).
2. base64 -w0 keystore-release.jks to produce the secret value.
3. gh secret set ANDROID_RELEASE_KEYSTORE_BASE64 --body "$(base64 -w0 keystore-release.jks)" (and the seven others).
4. Confirmation that the keystores are stored somewhere safe outside the repo before they're deleted from disk.

Wait for the user to confirm secrets are populated before merging the PR — otherwise the next prod CD run will hit the require-release: 'true' guard and fail.

Verification plan

Before considering the work done:

1. Local: with key.properties absent, flutter run --release and flutter build apk --release --flavor production succeed (debug fallback).
2. Local: with key.properties present and a test keystore generated, the produced APK passes apksigner verify --print-certs and shows the test key's fingerprint.
3. CI (prod): temporarily push a no-op commit; download the APK from the cd-app run artifact; verify the fingerprint matches the canonical one. Run twice — fingerprints must be identical.
4. CI (PR): open a draft PR; verify the dev APK installs over a previous PR's dev APK without uninstalling.
5. Guard: temporarily un-set ANDROID_RELEASE_KEYSTORE_BASE64 in a fork or workflow_dispatch run; verify the build fails fast with the configured error message.
6. Regression: re-verify the AAB published by the next tagged release with apksigner verify --verbose --print-certs jeeves-<ver>.aab.

Risks & open questions

• Profile vs release for PR builds — see §5. Need user confirmation before implementing.
• apksigner availability in CI — flutter-action installs Android command-line tools but does not always include the latest build-tools. If the verification step's find returns empty, fall back to skipping verification (warn, don't fail) since the build itself succeeding with a real signing config is the primary check.
• Per-flavor signingConfig in Kotlin DSL — minor risk that AGP's resolution of "flavor signingConfig wins over buildType signingConfig" doesn't behave as expected. Mitigation: if it misbehaves, switch to setting buildTypes.release.signingConfig via afterEvaluate or a Gradle expression that inspects the active variant's flavor name. Verify on the first local build.
• Where do team secrets live today? — RELEASES.md needs to point to the canonical secret-storage location. Confirm with user (1Password / Bitwarden / other) before writing that section.

Suggested commit/PR breakdown

One PR is appropriate — the change is cohesive and partial states are unsafe (a Gradle config that references missing properties would break local builds for everyone). Order commits within the PR:

1. chore(android): load signingConfigs from key.properties — Gradle changes + verify local debug fallback still works.
2. ci: add setup-android-signing composite action — the action, no callers yet.
3. ci(cd-app,pr-apk): sign with project keystores — wire the action into both workflows.
4. docs(releases): document Android signing keys and rotation — RELEASES.md updates.

[trixy-the-ai-bot]

Implementation complete.

Implemented per-flavor Android release signing: added a composite setup-android-signing action, wired it into cd-app.yml (with require-release: 'true' and an apksigner verify step) and pr-apk.yml (dev key, soft fallback), updated app/android/app/build.gradle.kts to load key.properties and configure release/devRelease signing, and documented the scheme in docs/RELEASES.md. Verification (build_runner, flutter analyze, 671 tests) is clean; out-of-process keystore generation and setting the eight ANDROID_* GitHub secrets are still owed before the next prod CD run.