komikku/docs/forgejo-release-runner.md

Forgejo releases and Obtainium

Forgejo Actions workflow: .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:

   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:

base64 -w0 your-release.keystore

Runner label

The workflow uses:

runs-on: desktop-release

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

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:

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):

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 on your device.
2. Add app → Override source: Forgejo (required for self-hosted instances).
3. Repository URL, e.g. https://forgejo.example/youruser/komikku (no /releases suffix).
4. Enable Allow insecure HTTP or disable SSL verification if Forgejo uses a self-signed certificate.
5. APK filter (regex): Komikku-arm64-v8a\.apk (or Komikku-universal\.apk).
6. Trim version string (regex): ^v?([0-9]+\.[0-9]+\.[0-9]+) — needed for fork tags like v1.13.6-forgejo.39.
7. Wait until the Forgejo release workflow has finished before adding or updating the app.

Direct download URL pattern (for reference):

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.