yellowjacket/docs/android-release.md

Releasing the Android APK

.gitea/workflows/android-apk.yml builds a signed arm64-v8a APK on every v* tag and publishes it to Gitea's generic package registry, which is readable without credentials — which is what lets Obtainium poll a plain URL with no token. It also attaches the same file to the Gitea release, which is what a person looking at the release page downloads.

Tags are not pushed by hand any more. .gitea/workflows/release.yml reads the Conventional Commits on every merge to main, decides the version, and pushes the tag this workflow is keyed on — so releasing the APK means merging a fix: or feat: commit, not running git tag. The workflow_dispatch path below remains, for rebuilding a tag that already exists.

The 1.x installs cannot be upgraded to 0.0.x

Releases restarted at 0.0.1 when they became automatic (plan 017). versionCode is computed as maj*10000 + min*100 + pat, so 0.0.1 is 1 against the 10300 an installed 1.3.0 build carries — and Android refuses a downgrade outright, with INSTALL_FAILED_VERSION_DOWNGRADE.

The only way through is adb uninstall app.yellowjacket (or the launcher's own uninstall) before installing 0.0.1, and that takes the device's library, playlists and play counts with it — the same loss the signing key section below exists to prevent, arrived at from the other direction. This was chosen deliberately over offsetting versionCode by a constant, on the grounds that the honest number is worth one reinstall while an offset is permanent. The workflow prints a warning whenever the code it computes is below 10600.

https://git.ljones.me/api/packages/yonlu/generic/yellowjacket-android/latest/yellowjacket.apk

A versioned copy is kept alongside it at …/yellowjacket-android/<version>/yellowjacket-<version>.apk.

The app on the device is app.yellowjacket. Its launcher activity is com.wails.app.MainActivity — a different package, because that is the Wails scaffold's Java package and renaming it would mean renaming its source. Every am start needs the fully-qualified form.

The signing key is the thing you cannot lose

Android refuses to update an app whose signing certificate changed. There is no override and no recovery: the only way to install a build signed with a different key is to uninstall first, which takes the user's library, playlists and play counts with it. The key therefore outlives every other secret in this repo.

Two consequences are wired into the workflow rather than left to discipline. It refuses to build when ANDROID_KEYSTORE_B64 is absent, instead of falling through to Gradle's debug-keystore default — a debug key differs between every machine and every CI runner, so a build signed with one is un-updatable from the moment it is installed. And it refuses to publish an APK whose certificate reads CN=Android Debug, which is the same rule enforced one step later, on the artifact rather than the configuration.

Creating it

keytool -genkeypair -v \
  -keystore yellowjacket-release.jks \
  -alias yellowjacket \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -storepass '<a long random password>' \
  -dname "CN=YellowJacket, O=Shadow-Puppet, C=GB"

Do not pass -keypass. keytool has produced PKCS12 keystores by default since JDK 9 — the .jks extension does not change the format — and PKCS12 cannot hold a key password distinct from the store password. Given one it tells you so and ignores it:

Warning: Different store and key passwords not supported for PKCS12
KeyStores. Ignoring user-specified -keypass value.

So there is one password. Asking for a second is how someone sets a wrong value and then debugs Gradle at midnight.

Back the .jks up somewhere that is not this repository and not this server. Record the certificate fingerprint the build prints (Signer #1 certificate SHA-256 digest); if it ever changes, updates have already broken.

The secrets

Repository → Settings → Actions → Secrets.

Secret	Required	Notes
ANDROID_KEYSTORE_B64	yes	base64 -w0 yellowjacket-release.jks
ANDROID_KEYSTORE_PASSWORD	yes	the -storepass above
ANDROID_KEY_ALIAS	no	defaults to yellowjacket
ANDROID_KEY_PASSWORD	no	defaults to the store password, and per the PKCS12 note it cannot differ
PACKAGE_TOKEN	already set	shared with arch-package.yml; publishes to the registry

base64 -w0 yellowjacket-release.jks   # paste as ANDROID_KEYSTORE_B64

Cutting a release

git tag v1.3.1
git push origin v1.3.1

That is the whole trigger. homebrew-formula.yml keys on the same tag, so the desktop formula and the APK are cut together. The version code Android orders releases by is derived from the tag — 1.3.1 → 10301, monotonic as long as minor and patch stay below 100 — so do not publish 1.100.0, and never move a tag that has already been built.

workflow_dispatch rebuilds without a new tag, taking an explicit version input or falling back to the latest v* tag.

What the workflow checks before publishing

• the APK exists and is non-empty;
• it carries exactly one ABI (native-code: 'arm64-v8a'). x86_64 Android cannot run this app at all — modernc.org/libc issues a raw lstat syscall that Android's seccomp policy forbids, on every x86_64 device and not merely the emulator — so an x86_64 slice would be ~31 MB that runs nowhere, and its reappearance means someone put the ABI back in app/build.gradle without knowing that;
• its versionCode is the one derived from the tag;
• it is not signed with the debug key.

The keystore is also opened with keytool -list before Gradle runs, because Gradle only notices a bad password at :app:validateSigningRelease — a minute of build time in — and reports it as a missing file rather than a wrong password.

Caches, and the first run

The job mounts four cache volumes; on a cold runner the first build is slow and everything after it is not.

Volume	Holds	Cold cost
/cache/android-sdk	SDK, platform, build-tools, NDK r26d	~2 GB
/cache/gradle	GRADLE_USER_HOME — wrapper + AGP graph	~700 MB
/cache/tool	the Go toolchain (shared with ci.yml)	~200 MB
/cache/pnpm-store	pnpm store (shared with ci.yml)	—

Every path must be inside the runner's valid_volumes allowlist. One that is not makes the job fail to start rather than silently skip the mount.

The NDK is pinned to r26d (26.3.11579264). Newer NDKs have broken the Wails Android build before; it is a version, not a floor.

Building one locally

make android          # unsigned-ish: debug key, versionCode 1, 0.0.0
YJ_VERSION=1.3.1 YJ_VERSION_CODE=10301 \
ANDROID_KEYSTORE_FILE=$PWD/yellowjacket-release.jks \
ANDROID_KEYSTORE_PASSWORD=... ANDROID_KEY_ALIAS=yellowjacket \
  make android        # what CI produces

Running it is a separate tier — see .pi/skills/yellowjacket-dev/references/android-tier.md, and read its first section before you try, because a failing Android build looks exactly like a working one.