Release signing and a tag-triggered release workflow

.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+# Push a tag like v1.1.0 (after bumping the version in pubspec.yaml) to build a signed
+# release APK and publish it as a GitHub Release.
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: "temurin"
+          java-version: "17"
+
+      - uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "3.47.4"
+          channel: "stable"
+
+      - run: flutter pub get
+      - run: flutter analyze
+      - run: flutter test
+        env:
+          TZ: Europe/Warsaw
+
+      # Never publish a debug-signed APK: it can't update a release install.
+      - name: Write release signing config
+        env:
+          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+        run: |
+          if [ -z "$ANDROID_KEYSTORE_BASE64" ]; then
+            echo "::error::Set the ANDROID_KEYSTORE_BASE64, ANDROID_KEYSTORE_PASSWORD and ANDROID_KEY_ALIAS secrets first"
+            exit 1
+          fi
+          mkdir -p android/keystore
+          echo "$ANDROID_KEYSTORE_BASE64" | base64 -d > android/keystore/release-key.jks
+          cat > android/key.properties <<EOP
+          storePassword=$ANDROID_KEYSTORE_PASSWORD
+          keyPassword=$ANDROID_KEYSTORE_PASSWORD
+          keyAlias=$ANDROID_KEY_ALIAS
+          storeFile=keystore/release-key.jks
+          EOP
+
+      - run: flutter build apk --release
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: build/app/outputs/flutter-apk/app-release.apk
+          generate_release_notes: true

AGENTS.md

@@ -406,8 +406,9 @@ done; what's next is judgment, not a fixed checklist:
   it *always* uninstalls first when the app is present. `--debug` doesn't help; a first
   version of this guardrail wrongly said it did. **Never `flutter run` either**: its
   Android install (`android_device.dart`, `installApp`) silently falls back to uninstall +
-  reinstall whenever `adb install -r` fails. Stay on debug builds (release is signed with
-  the same debug key per `build.gradle.kts`, but drops the debug test-alarm button). No
+  reinstall whenever `adb install -r` fails. Stay on debug builds: a release build is signed
+  with the release key when `android/key.properties` exists (see "Releases"), so it can't
+  replace the debug-signed copy on the phone -- and an uninstall to "fix" that is the wipe. No
   `adb uninstall`, no `pm clear`. If an install fails, stop and ask -- the "fix" is an uninstall, which is the
   wipe. This already happened once (2026-09-24, see "Current state") and cost the user
   all their data.
@@ -443,6 +444,20 @@ done; what's next is judgment, not a fixed checklist:
   descriptions or comments -- whatever an agent environment's default attribution says.
   A single "Generated with Claude Code" line in a PR is fine; don't add it twice.
 
+## Releases
+
+- Bump `version:` in `pubspec.yaml`, merge, then `git tag vX.Y.Z && git push origin vX.Y.Z`.
+  `.github/workflows/release.yml` builds a signed release APK and publishes a GitHub Release.
+- Signing: `android/key.properties` + `android/keystore/release-key.jks` (both gitignored).
+  The key and its password are backed up in `~/.android/keystores/dosekeeper-release.*` on
+  the user's machine (made 2026-10-31; losing it means no update can ever install over a
+  release install). CI reads the GitHub secrets `ANDROID_KEYSTORE_BASE64`,
+  `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_ALIAS` and refuses to publish without them.
+  Without `key.properties` a local release build falls back to the debug key.
+- **The phone runs a debug-signed build.** A release APK can't install over it (Android
+  refuses: different signature). Moving the phone to release builds means Settings → backup,
+  uninstall, install the release, restore -- the user's decision, never an agent's.
+
 ## Git workflow
 
 Remote: `https://github.com/SusieeTheLinuxUser/dosekeeper` (public, MIT).

android/app/build.gradle.kts

@@ -1,9 +1,20 @@
+import java.util.Properties
+
 plugins {
     id("com.android.application")
     // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
     id("dev.flutter.flutter-gradle-plugin")
 }
 
+// Release signing, from android/key.properties (gitignored). CI writes it from secrets: see
+// .github/workflows/release.yml. Without it a release build falls back to the debug key.
+val keystoreProperties = Properties()
+val keystorePropertiesFile = rootProject.file("key.properties")
+val hasReleaseSigning = keystorePropertiesFile.exists()
+if (hasReleaseSigning) {
+    keystoreProperties.load(keystorePropertiesFile.inputStream())
+}
+
 android {
     namespace = "dev.susiee.dosekeeper"
     compileSdk = flutter.compileSdkVersion
@@ -26,11 +37,20 @@ android {
         versionName = flutter.versionName
     }
 
+    signingConfigs {
+        if (hasReleaseSigning) {
+            create("release") {
+                storeFile = rootProject.file(keystoreProperties.getProperty("storeFile"))
+                storePassword = keystoreProperties.getProperty("storePassword")
+                keyAlias = keystoreProperties.getProperty("keyAlias")
+                keyPassword = keystoreProperties.getProperty("keyPassword")
+            }
+        }
+    }
+
     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")
+            signingConfig = signingConfigs.getByName(if (hasReleaseSigning) "release" else "debug")
         }
     }
 }