ci(forgejo): add manual release dispatch and refresh release docs

Allow rebuilding an existing tag via workflow_dispatch and document
Obtainium-friendly asset names, secrets, and runner setup.

Co-authored-by: Cursor <cursoragent@cursor.com>

.forgejo/workflows/build_release.yml

@@ -5,6 +5,12 @@ on:
   push:
     tags:
       - v*
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. v1.13.6). Must already exist on the remote.'
+        required: true
+        type: string
 
 permissions:
   contents: write
@@ -21,6 +27,7 @@ jobs:
         shell: bash
         env:
           FORGEJO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DISPATCH_TAG: ${{ github.event.inputs.tag }}
         run: |
           set -euo pipefail
           rm -rf .git
@@ -28,7 +35,11 @@ jobs:
           origin_url="${GITHUB_SERVER_URL#https://}"
           origin_url="${origin_url#http://}"
           git remote add origin "https://copilot:${FORGEJO_TOKEN}@${origin_url}/${GITHUB_REPOSITORY}.git"
-          git -c http.sslVerify=false fetch --tags --prune origin "${GITHUB_SHA}"
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
+            git -c http.sslVerify=false fetch --tags --prune origin "refs/tags/${DISPATCH_TAG}"
+          else
+            git -c http.sslVerify=false fetch --tags --prune origin "${GITHUB_SHA}"
+          fi
           git checkout --force FETCH_HEAD
 
       - name: Set up JDK
@@ -86,7 +97,11 @@ jobs:
         run: |
           set -euo pipefail
 
-          version_tag="${GITHUB_REF_NAME:-${GITHUB_REF#refs/tags/}}"
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
+            version_tag="${{ github.event.inputs.tag }}"
+          else
+            version_tag="${GITHUB_REF_NAME:-${GITHUB_REF#refs/tags/}}"
+          fi
           version_display="$(printf '%s' "$version_tag" | sed -E 's/^v//' )"
           previous_tag="$(git tag --list 'v*' --sort=-version:refname | grep -Fxv "$version_tag" | head -n 1 || true)"
           upstream_repo="komikku-app/komikku"

docs/forgejo-release-runner.md

@@ -1,62 +1,80 @@
-# Forgejo release runner
+# Forgejo releases and Obtainium
 
-This repository now includes a Forgejo-native release workflow at `.forgejo/workflows/build_release.yml`.
+Forgejo Actions workflow: [`.forgejo/workflows/build_release.yml`](../.forgejo/workflows/build_release.yml)
 
 ## What it does
 
-- Triggers on tags matching `v*`
+- Triggers on tags matching `v*`, or manually via **Actions → Forgejo Release Builder → Run workflow**
-- Builds the release APKs
+- Builds release APKs (`assembleRelease -Penable-updater -Pdisable-code-shrink`, no telemetry)
-- Signs the APKs
+- Signs APKs with your release keystore
-- Creates or updates a draft release through the Forgejo API
+- Creates or updates a Forgejo release and uploads APK assets
-- Uploads the APKs and a zipped ProGuard mapping as release assets
+- Publishes stable Obtainium-friendly asset names alongside versioned files
 
-The workflow intentionally avoids GitHub-only artifact and release actions so it can run on Forgejo with a self-hosted runner.
+The workflow uses shell + Forgejo API calls only (no GitHub-only release actions), so it runs on self-hosted Forgejo runners.
+
+## Cut a release
+
+1. Bump `versionCode` / `versionName` in `app/build.gradle.kts` if needed.
+2. Commit and push to your default branch.
+3. Create and push an annotated tag:
+
+   ```sh
+   git tag -a v1.13.6 -m "v1.13.6"
+   git push origin v1.13.6
+   ```
+
+4. Forgejo Actions builds, signs, and publishes the release automatically.
+
+To **rebuild an existing tag** (e.g. after fixing signing secrets), use **Run workflow** and enter the tag name. The tag must already exist on the remote.
 
 ## Required repository secrets
 
-Set these secrets in the Forgejo repository settings:
+Configure under **Repository → Settings → Actions → Secrets**:
 
-- `GOOGLE_SERVICES_JSON`
+| Secret | Description |
-- `GOOGLE_CLIENT_SECRETS_JSON`
+|--------|-------------|
-- `SIGNING_KEY`
+| `SIGNING_KEYSTORE_B64` | Base64-encoded release keystore (`.jks` / `.keystore`) |
-- `ALIAS`
+| `SIGNING_KEYSTORE_PASSWORD` | Keystore password |
-- `KEY_STORE_PASSWORD`
+| `SIGNING_KEY_ALIAS` | Key alias inside the keystore |
-- `KEY_PASSWORD`
+| `SIGNING_KEY_PASSWORD` | Key password |
 
-`secrets.GITHUB_TOKEN` is used as the Forgejo-provided built-in token for the release API calls.
+`secrets.GITHUB_TOKEN` is the built-in Forgejo Actions token used for release API calls (no extra setup).
+
+Encode a keystore for the secret:
+
+```sh
+base64 -w0 your-release.keystore
+```
 
 ## Runner label
 
 The workflow uses:
 
 ```yaml
-runs-on: forgejo-release
+runs-on: desktop-release
 ```
 
-Register a runner with a matching label. Host mode is the simplest option for Android builds:
+Register a self-hosted runner with a matching label. Host mode is simplest for Android builds:
 
 ```sh
 forgejo-runner register \
-  --instance https://192.168.1.155:3030 \
+  --instance https://your-forgejo.example \
   --token <registration-token> \
   --name komikku-release \
-  --labels "forgejo-release:host"
+  --labels "desktop-release:host"
 ```
 
 ## Runner prerequisites
 
-Install these on the runner host before enabling the workflow:
+Install on the runner host:
 
-- Git
+- Git, curl, jq, zip
-- curl
-- zip
-- Python 3
 - JDK 17
 - Android SDK command-line tools
 - Android platform `android-35`
-- Android build-tools `35.0.1`
+- Android build-tools `35.0.0` (or newer; workflow installs via `sdkmanager` if missing)
 
-Recommended environment variables on the runner host:
+Recommended environment:
 
 ```sh
 export ANDROID_HOME=/opt/android-sdk
@@ -64,15 +82,48 @@ export ANDROID_SDK_ROOT=/opt/android-sdk
 export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"
 ```
 
-## Suggested setup flow
+Optional persistent Gradle cache (speeds up repeat builds):
 
-1. Enable Actions on the Forgejo instance and repository.
+```sh
-2. Register the `forgejo-release` runner.
+export KOMIKKU_GRADLE_CACHE="$HOME/.cache/komikku-ci-gradle"
-3. Add the required repository secrets.
+```
-4. Push a test tag such as `v0.0.0-forgejo.1`.
+
-5. Open the draft release in Forgejo and verify the uploaded APKs.
+## Release assets
+
+Versioned (one set per tag):
+
+- `Komikku-v1.13.6.apk` — universal
+- `Komikku-arm64-v8a-v1.13.6.apk`
+- `Komikku-armeabi-v7a-v1.13.6.apk`
+- `Komikku-x86-v1.13.6.apk`
+- `Komikku-x86_64-v1.13.6.apk`
+- `Komikku-mapping-v1.13.6.zip` — ProGuard mapping (when present)
+
+Stable aliases (same filename every release; best for Obtainium):
+
+- `Komikku-universal.apk`
+- `Komikku-arm64-v8a.apk`
+
+## Obtainium
+
+Obtainium can install directly from Forgejo release assets.
+
+1. Install [Obtainium](https://github.com/ImranR98/Obtainium) on your device.
+2. **Add app** → source type **Forgejo** (or **Gitea** on older Obtainium).
+3. Enter your repository URL, e.g. `https://forgejo.example/youruser/komikku`.
+4. Set **APK filter** to a stable asset name:
+   - Most phones: `Komikku-arm64-v8a.apk`
+   - Universal fallback: `Komikku-universal.apk`
+5. Obtainium reads the latest `v*` release tag; version is parsed from the tag (e.g. `v1.13.6` → `1.13.6`).
+
+Direct download URL pattern (for reference):
+
+```text
+https://forgejo.example/<owner>/<repo>/releases/download/<tag>/Komikku-arm64-v8a.apk
+```
 
 ## Notes
 
-- The existing GitHub workflows under `.github/workflows/` remain unchanged.
+- GitHub workflows under `.github/workflows/` are unchanged; they target GitHub Actions and upstream secrets.
-- The Forgejo release notes are generated from git history, so they do not depend on the GitHub compare API.
+- Release notes are generated from git history between the previous and current `v*` tag.
+- Unsigned APKs are built internally but only signed APKs are uploaded to the release.