komikku/docs/forgejo-release-runner.md

# Forgejo releases and Obtainium

Forgejo Actions workflow: [`.forgejo/workflows/build_release.yml`](../.forgejo/workflows/build_release.yml)

## What it does

- Triggers on tags matching `v*`, or manually via **Actions → Forgejo Release Builder → Run workflow**
- Builds release APKs (`assembleRelease -Penable-updater -Pdisable-code-shrink`, no telemetry)
- Signs APKs with your release keystore
- Creates or updates a Forgejo release and uploads APK assets
- Publishes stable Obtainium-friendly asset names alongside versioned files

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

Configure under **Repository → Settings → Actions → Secrets**:

| Secret | Description |
|--------|-------------|
| `SIGNING_KEYSTORE_B64` | Base64-encoded release keystore (`.jks` / `.keystore`) |
| `SIGNING_KEYSTORE_PASSWORD` | Keystore password |
| `SIGNING_KEY_ALIAS` | Key alias inside the keystore |
| `SIGNING_KEY_PASSWORD` | Key password |

`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: desktop-release
```

Register a self-hosted runner with a matching label. Host mode is simplest for Android builds:

```sh
forgejo-runner register \
  --instance https://your-forgejo.example \
  --token <registration-token> \
  --name komikku-release \
  --labels "desktop-release:host"
```

## Runner prerequisites

Install on the runner host:

- Git, curl, jq, zip
- JDK 17
- Android SDK command-line tools
- Android platform `android-35`
- Android build-tools `35.0.0` (or newer; workflow installs via `sdkmanager` if missing)

Recommended environment:

```sh
export ANDROID_HOME=/opt/android-sdk
export ANDROID_SDK_ROOT=/opt/android-sdk
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"
```

Optional persistent Gradle cache (speeds up repeat builds):

```sh
export KOMIKKU_GRADLE_CACHE="$HOME/.cache/komikku-ci-gradle"
```

## 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

- GitHub workflows under `.github/workflows/` are unchanged; they target GitHub Actions and upstream secrets.
- 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.