clockula/docs/RELEASING.md

Clockula — releasing

Clockula is distributed through a self-hosted F-Droid repo (on Hetzner) and a Codeberg release per version carrying the signed APK as a direct download. Both are produced automatically by .gitea/workflows/release.yaml when a bumped versionName reaches main — the pipeline builds and publishes that version, then creates the matching vX.Y.Z tag and the releases itself. The parallel Gitea release is the changelog of record on the build instance and carries no APK assets.

Codeberg is the canonical forge; Gitea is build infrastructure. See Two forges, one repo for how the two are wired.

While Clockula is pre-1.0 (versionName starts with 0.), every release is flagged as a pre-release. This happens automatically and graduates to a stable release at 1.0.0 — no manual toggling.

---

The source of truth: the committed version

A release is defined by the versionName/versionCode committed in app/build.gradle.kts — not by a hand-pushed tag:

• versionName = MAJOR.MINOR.PATCH (e.g. 0.2.0)
• versionCode = MAJOR*10000 + MINOR*100 + PATCH (0.2.0 → 200, 1.3.4 → 10304)

So MINOR and PATCH each have room for 0–99. The release pipeline reads versionName, pins versionCode to the derived value, builds, publishes, and — once the APK is live — creates the tag v<versionName> at that commit. The tag is an output of a successful release, not its trigger, so a tag always marks a fully-shipped version (and a failure before publish leaves no tag, so re-running the workflow safely retries).

---

Cutting a release

1. Assemble the release branch. Create release/vX.Y.Z and merge the feature/fix branches for this release into it. Everything below happens on that branch, before it reaches main.

2. Update CHANGELOG.md. Move the ## [Unreleased] items under a new ## [X.Y.Z] heading (Keep a Changelog format). The text between that heading and the next ## [ becomes both the Gitea release notes and the F-Droid per-version "What's New". The heading must match the version exactly.

3. Bump the committed versionName (and versionCode) in app/build.gradle.kts. This bump is what triggers the release when the branch merges to main. Then run

   scripts/sync_changelog_to_fastlane.sh
   

   and commit the generated fastlane/metadata/android/en-US/changelogs/<versionCode>.txt — this is what makes the official F-Droid listing (which harvests the changelog from the tagged source tree) show this version. The self-hosted pipeline regenerates it regardless, so forgetting only affects the official listing.

4. Verify the release build on a real device — the mandatory gate:

   scripts/verify-release.sh
   

   It builds the releaseTest variant (same R8 config as release, debug-signed with a .releasetest suffix so it installs alongside the real app) and resets it to a first-run state. Then, on the device:

   • launch from a clean / permission-not-granted state — the permission screen must appear, no crash;
   • grant tasks access — the task list must load;
   • create a task with a due reminder and confirm the notification fires;
   • exercise this release's headline changes.

   Only proceed once all of that passes on-device.

5. Merge release/vX.Y.Z into main. That's it — no manual tagging. The merge triggers release.yaml, which detects the new version, builds, signs, publishes to F-Droid, and creates the vX.Y.Z tag + Gitea release.

The releaseTest build type exists only for step 4 — it is never published. The pipeline always builds and signs the real release variant.

---

What the pipeline does

CI and release are split so a change is built once on its PR and only does release work when a merge actually cuts a release:

• ci.yaml (.forgejo/workflows/, on pull_request, Codeberg) — the reproducible-release invariant guard (scripts/check_reproducible_release.sh), then lint + unit tests + a debug assemble and a Trivy scan, once per PR. Docs/metadata-only PRs skip the Android build but still report a green CI check.
• translations.yaml (.forgejo/workflows/, on pull_request, Codeberg) — an SDK-free parity check (scripts/check_translations.py) over values-*/strings.xml, so Weblate PRs get fast feedback. Runs on every PR without a path filter, so the required Translations / check status is always reported.
• renovate.yml (.gitea/workflows/, Mondays 05:00 UTC plus workflow_dispatch, Gitea) — the dependency sweep. Runs the pinned Renovate image as its job container and targets Codeberg's API; the cadence lives here, not in renovate.json5, so the two don't double-gate.
• release.yaml (.gitea/workflows/, on push to main plus workflow_dispatch, Gitea) — a cheap detect job reads versionName and checks Codeberg for a tag for it. Only when there isn't one does the release job run: unit tests on the merged commit, pin versionCode, build & sign the release APK with the app key, copy it into the F-Droid repo, generate the per-version changelog from the fastlane tree, re-sign the index with the repo key, upload repo/ + metadata/, then create the vX.Y.Z tag + Gitea release (CHANGELOG section as notes, flagged pre-release while MAJOR is 0), attach the R8 mapping.txt, and publish the release on Codeberg with the signed APK + a SHA-256 checksum. Ordinary merges with no version bump fall through detect and do nothing.

The pipeline ends with a separate play job that uploads the App Bundle to Google Play. It runs last and in isolation so a Play rejection cannot endanger a release that has already shipped to F-Droid and Codeberg, and it skips cleanly until Play is configured.

Codeberg direct-download channel

Alongside F-Droid, each release is published on the Codeberg repo (jlmakiola/clockula) as a plain download for users who don't want F-Droid. Releases aren't git objects and don't sync with the push mirror in either direction, so the pipeline pushes the vX.Y.Z tag straight to Codeberg, creates the release over the Codeberg API, and attaches clockula_v<version>.apk + its .sha256. It's the same APK the F-Droid repo serves (same app key), so it adds no trust surface. It skips cleanly if CODEBERG_RELEASE_TOKEN is unset, but it is not continue-on-error: through 0.2.1–0.3.2 this step reported green while never once publishing, which is how a crash-fix release reached F-Droid but not the Codeberg/Obtainium users who needed it. A broken mirror fails the release loudly.

One-time setup: the Codeberg repo's Releases unit must be enabled and a CODEBERG_RELEASE_TOKEN secret (Codeberg access token, write:repository scope — it pushes the tag as well as creating the release) added to Gitea Actions.

Google Play channel

Play is a third channel alongside F-Droid and the Codeberg download, and it is the only one that gets a different artifact and a different signature.

Artifact. Play takes an App Bundle (bundleRelease), not the APK. It is a second output of the same source and the same signing config — never a repackage of the published APK, which stays untouched so the F-Droid reproducibility guarantee is unaffected. The bundle is built at the very end of the release job, after everything else has shipped, and both it and the handoff to the play job are continue-on-error — nothing Play-related may take down a release that is already published. The handoff uses a patched upload-artifact/download-artifact fork pinned to a commit: the official v4 actions read any non-github.com forge as an unsupported GHES instance and refuse to run on Gitea (go-gitea/gitea#36024). dependenciesInfo stays disabled for the bundle too; Play's "app dependencies" report is optional and re-enabling it would break reproducibility.

Signature — read this before assuming an update path exists. Play App Signing is mandatory for new apps, and Google generates and holds the app signing key. The release keystore in CI is registered only as the upload key: Play verifies uploads with it, then re-signs with Google's key before delivery. Consequences, accepted deliberately:

• A Play install and an F-Droid install have different signatures and cannot update each other. Switching channels requires uninstall + reinstall, which loses nothing (all data lives in the system calendar provider) but must be stated wherever both channels are advertised.
• Losing the upload key is recoverable — request an upload-key reset in the Play Console. Losing the app key still is not, for F-Droid.

Build and signing are not fastlane's job. Gradle does both, exactly as before. fastlane appears only as the Play Developer API client (supply), because the store listing already lives in fastlane/metadata/android/ — the same tree the official F-Droid repo harvests. One metadata source, two stores.

What gets uploaded per release: the AAB, plus the per-version "What's New" from fastlane/metadata/android/en-US/changelogs/<versionCode>.txt — the hand-written summary from step 3, which is why it must stay under 500 characters: Play rejects a longer one. Listing text is not touched — an accidental overwrite of a live listing triggers a Play policy review. Sync it deliberately with bundle exec fastlane listing.

Screenshots and graphics are skipped, because the committed assets satisfy F-Droid but not Play:

Asset	Committed	Play requires
phoneScreenshots/*.png	1280×2856, 32-bit RGBA	long edge ≤ 2× short edge (so ≤ 2560), 24-bit PNG, no alpha
icon.png	512×512, 24-bit RGB	512×512, 32-bit PNG
featureGraphic.png	missing	required, exactly 1024×500

Until those are fixed, Play's graphics are managed by hand in the console. Then pass images:true to the listing lane.

Track. Uploads go straight to production at a full rollout (PLAY_RELEASE_STATUS=completed). The merge to main is already the human gate — a release only gets there after on-device review — so a second manual promotion in the Play Console added delay without adding a decision. Set the PLAY_TRACK repo variable (e.g. internal) to stage a release instead, or PLAY_RELEASE_STATUS=draft to hold it unpublished.

Manual re-sign / recovery

A manual workflow_dispatch of the release workflow runs a re-sign-only path: detect reports it's not a release, so the release job skips the APK build, the version pin, and tag/release creation, and just re-signs the existing F-Droid index with the configured repo key and re-uploads. Use this for key rotation or repo recovery without publishing a new app version.

---

Two forges, one repo

Codeberg (jlmakiola/clockula) is canonical — git, issues, PRs, tags and releases. The self-hosted Gitea instance is build infrastructure: it holds the signing key, publishes the F-Droid repo, and runs the release pipeline. Codeberg push-mirrors main and tags to Gitea, and a bumped versionName arriving there triggers release.yaml exactly as before.

Workflows are separated by directory, not by conditionals. Forgejo looks in .forgejo/workflows → .gitea/workflows → .github/workflows and stops at the first that exists; Gitea doesn't know .forgejo/ at all:

Directory	Runs on	Contains	Secrets
.forgejo/workflows/	Codeberg	ci.yaml, translations.yaml	none
.gitea/workflows/	Gitea	release.yaml, renovate.yml	signing key, F-Droid, Hetzner, bot tokens

The line is drawn at secrets, not at CI-vs-release. That's what makes fork PRs safe: everything a contributor can trigger lives in .forgejo/ and can reference no secret. Renovate stays on the Gitea runner even though it opens PRs on Codeberg — it talks to Codeberg's API rather than moving its token onto the contributor-facing runner. detect (and the Renovate job) additionally carries a github.repository_owner == 'makiolaj' guard, because the directory split only holds while .forgejo/ is non-empty — empty it and Codeberg would fall back to .gitea/ and run the release pipeline on the contributor-facing runner.

Two consequences worth remembering:

• detect reads tags from Codeberg, not from the Gitea instance it runs on. Push mirroring is git push --mirror, so a tag minted on Gitea is deleted by the next sync until the Codeberg tag push propagates back. Asking Gitea inside that window would re-cut a shipped release.
• Any ref that exists only on Gitea gets deleted by the mirror. That's correct under Codeberg-canonical, but don't debug a "vanished" branch without remembering it.

floret-kit is a submodule of this repo and follows the same move: .gitmodules points at https://codeberg.org/jlmakiola/floret-kit.git, so a clone resolves without reaching the personal Gitea instance. The Gitea copy is kept — every existing tag records the old submodule URL, so rebuilds of past releases still resolve.

---

Secrets (Gitea → repo Settings → Actions → Secrets)

The workflow fails loudly if the F-Droid ones are missing — it will never auto-generate a repo key (that would rotate the repo fingerprint and break every user's pinned repo).

Secret	Purpose
KEYSTORE_BASE64, KEY_PASSWORD, KEY_ALIAS	App signing key — signs the APK. Losing it means existing installs can't be updated.
FDROID_KEYSTORE_BASE64	F-Droid repo signing key (keystore.p12, base64). Signs the repo index.
FDROID_CONFIG_BASE64	F-Droid config.yml (base64) — repo metadata + keystore passwords.
HETZNER_HOST, HETZNER_USER, HETZNER_PASS	Upload target for the F-Droid repo.
GITHUB_TOKEN	Provided by Gitea Actions; used to create the release + attach assets.
CODEBERG_RELEASE_TOKEN	Codeberg access token (write:repository scope) — pushes the tag to Codeberg, creates the release there and uploads the APK/checksum. If unset the step skips; if set and failing, the release fails.
PLAY_SERVICE_ACCOUNT_JSON	Google Cloud service-account key (full JSON) with Play Console access — uploads the AAB. If unset, the play job skips cleanly, which is the expected state for the whole pre-1.0 run.
RENOVATE_TOKEN	Codeberg bot-account token — repo read/write + PR scope on jlmakiola/clockula. Used only by renovate.yml.
GITHUB_COM_TOKEN	Read-only github.com PAT (no scopes). Without it Renovate's changelog lookups hit the 60/h anonymous rate limit and PRs arrive with empty release notes.

The app key signs APKs; the repo key signs the index (its fingerprint is what users pin). Neither key nor config.yml is ever uploaded to the server — they live only in CI secrets and are reconstructed in-runner (nginx serves only repo/).

---

F-Droid metadata (single source of truth)

Store-listing text lives in fastlane/metadata/android/<locale>/ — the same tree the official F-Droid repo harvests from source. At release time scripts/fastlane_to_fdroid_localized.sh transforms it into the F-Droid repo's "localized" layout, so there is no second copy to maintain. The app-level control file (Categories/License/links) stays in fdroid-metadata/de.jeanlucmakiola.clockula.yml. Per-version changelogs are seeded into fastlane/.../en-US/changelogs/<versionCode>.txt by scripts/sync_changelog_to_fastlane.sh (step 3 above) and carried across by the transform.

---

Crash deobfuscation

Each release attaches mapping-<version>.txt.gz (the R8 mapping) to its Gitea release. To deobfuscate a user stacktrace, download the mapping for that version and run it through retrace.