docs(release): Android keystore rotation runbook + leak-recovery #220

New issue

Open

opened 2026-06-21 16:40:10 +00:00 by james · 0 comments

james commented

2026-06-21 16:40:10 +00:00

Owner

Context

The Android release pipeline (#187) signs the APK / AAB with a single keystore the maintainer holds via four Forgejo secrets (ANDROID_KEYSTORE_BASE64, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, ANDROID_KEY_PASSWORD). Android upgrade semantics require every subsequent release to be signed with the same keystore — if the key leaks, every installed APK has to be uninstalled before the user can install a re-signed replacement. There is no documented rotation procedure today.

Source

PR #207 ("Follow-ups worth filing"):

Key rotation tooling. Today the maintainer holds one keystore, no rotation flow. If it ever leaks, every installed APK has to be replaced via an uninstall-first upgrade.

Scope

Document the leak-recovery procedure in apps/client/README.md and docs/ci.md "Release pipeline":
- How to generate a new keystore (keytool -genkey ... flags identical to the original).
- How to rotate the four Forgejo secrets atomically.
- The user-facing impact: every Android user has to uninstall-then-install (no in-place upgrade).
- An announcement template the maintainer can post on the release page.
Consider Android v3 / Play Store APK signing key upgrade (separate flow that lets the user upgrade in place via a "lineage" signing scheme); document feasibility even if not implemented.
Add a scripts/release/rotate-android-keystore.sh helper (or just a runbook) that walks the maintainer through the rotation in order.
Add a release-time check that warns if the keystore fingerprint changes between builds (catches accidental rotation in CI).

Acceptance criteria

Runbook exists with the exact keytool command and Forgejo secrets to update.
User-impact statement (uninstall-first) is unambiguous and easy to find.
The release workflow logs the keystore fingerprint of the signing key (without leaking it) so a rotation is auditable in the run output.
Optional: a signing-key-fingerprint.txt artifact (or release-page note) records the fingerprint each release was signed with, so an installed user can verify a planned rotation is legitimate.

Out of scope

Implementing Play Store distribution (separate concern — idea.md doesn't commit Carol to the Play Store).
iOS keystore rotation (iOS is out of scope per idea.md).

Composes with

#187 (closed — signed APK pipeline).
ADR-0014 (release pipeline).

## Context The Android release pipeline (#187) signs the APK / AAB with a single keystore the maintainer holds via four Forgejo secrets (`ANDROID_KEYSTORE_BASE64`, `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_ALIAS`, `ANDROID_KEY_PASSWORD`). Android upgrade semantics require every subsequent release to be signed with the same keystore — if the key leaks, every installed APK has to be uninstalled before the user can install a re-signed replacement. There is no documented rotation procedure today. ## Source PR #207 ("Follow-ups worth filing"): > Key rotation tooling. Today the maintainer holds one keystore, no rotation flow. If it ever leaks, every installed APK has to be replaced via an uninstall-first upgrade. ## Scope - Document the leak-recovery procedure in `apps/client/README.md` and `docs/ci.md` "Release pipeline": - How to generate a new keystore (`keytool -genkey ...` flags identical to the original). - How to rotate the four Forgejo secrets atomically. - The user-facing impact: every Android user has to uninstall-then-install (no in-place upgrade). - An announcement template the maintainer can post on the release page. - Consider Android v3 / Play Store APK signing key upgrade (separate flow that lets the user upgrade in place via a "lineage" signing scheme); document feasibility even if not implemented. - Add a `scripts/release/rotate-android-keystore.sh` helper (or just a runbook) that walks the maintainer through the rotation in order. - Add a release-time check that warns if the keystore fingerprint changes between builds (catches accidental rotation in CI). ## Acceptance criteria - [ ] Runbook exists with the exact `keytool` command and Forgejo secrets to update. - [ ] User-impact statement (uninstall-first) is unambiguous and easy to find. - [ ] The release workflow logs the keystore fingerprint of the signing key (without leaking it) so a rotation is auditable in the run output. - [ ] Optional: a `signing-key-fingerprint.txt` artifact (or release-page note) records the fingerprint each release was signed with, so an installed user can verify a planned rotation is legitimate. ## Out of scope - Implementing Play Store distribution (separate concern — `idea.md` doesn't commit Carol to the Play Store). - iOS keystore rotation (iOS is out of scope per `idea.md`). ## Composes with - #187 (closed — signed APK pipeline). - ADR-0014 (release pipeline).

james referenced this issue

2026-06-21 18:23:10 +00:00

feat(client): Tauri updater for the Linux Flatpak #228