Releasing the kiosk app
On this page
- The repo name
- 1. Create the release key (once)
- 2. Keep it safe
- 3. Add the four secrets to GitHub (once)
- Who can sign
- 3b. The radio bundle key (once)
- 3c. Web installer files
- 4. Release
- ABIs
- Raising targetSdk
- The secret store and downgrades
- Building a signed APK locally
- Signed test builds of a branch
- Debug builds and the release key
- Libraries
- The public API
- Cut a release
- What the workflow does
- If the validation wait times out
- Rotate the token or the signing key
Panels update themselves from GitHub Releases: the app lists
https://api.github.com/repos/GlassworksHQ/glassworks/releases, picks its own newest release
and shows the result in Home Assistant as update.s1_panel_app_update (on a panel added before #63;
update.glassworks_panel_app_update on one added before #260; a newer one starts with the device's
name, aqara_s1_plus_ on a new S1, Names)
(esphome.md). A release is built and published by
.github/workflows/release.yml when you push a v* or
aqara-s1-plus-v* tag. It holds one APK per ABI, each with its .sha256 (see ABIs):
s1-kiosk-<version>.apk, thearmeabi-v7aAPK the S1 runs, signed with the release key;s1-kiosk-arm64-v8a-<version>.apk, the same app forarm64-v8adevices;s1-kiosk-<version>.apk.sha256ands1-kiosk-arm64-v8a-<version>.apk.sha256, theirsha256sumlines.
The libraries in libs/ are released to Maven Central on their own tags: see Libraries.
Every release must be signed with the same key. Android only installs an update signed with the key of the installed app, and the app refuses anything else before trying. Lose the key and every panel needs a manual reinstall, which clears its settings.
The repo name
The repo started as aguilaair/aqara-s1-unleashed, moved to GlassworksHQ/aqara-s1-unleashed, and
was renamed to GlassworksHQ/glassworks on 2026-11-13. Panels on 0.4.3 and older ask
aguilaair/aqara-s1-unleashed, the name built into them, and reach the releases through GitHub's
redirects. A redirect only lasts while no repo exists at the old name, so never create or reuse
either old name, not even as an empty placeholder: it would cut off updates for every panel that
hasn't moved past 0.4.3.
1. Create the release key (once)
On your own computer, outside the repository. keytool comes with any JDK.
mkdir -p ~/secure && cd ~/secure
keytool -genkeypair -v \
-keystore s1kiosk-release.jks -storetype PKCS12 \
-alias s1kiosk -keyalg RSA -keysize 4096 -validity 10000 \
-dname "CN=S1 Kiosk, O=aqara-s1-unleashed"
keytoolasks for the keystore password twice; it is not echoed and not stored in your shell history. Use a long random one from your password manager.- PKCS12 keystores have one password for the store and the key, so the key password is the same.
-validity 10000is about 27 years (the Android documentation's recommendation is at least 25).
Write down the certificate fingerprint; it is public, and lets anyone check a release:
keytool -list -v -keystore ~/secure/s1kiosk-release.jks -alias s1kiosk | grep SHA256
The fingerprint is also committed in
tools/release/release-cert.sha256 (lowercase hex, no
colons). The release and test-build workflows refuse an APK signed with any other key
(tools/release/check-update-compat.sh), so a wrong or
swapped secret fails the build instead of shipping an update no panel can install. Rotating the key
means changing that file in the same PR as the secrets.
2. Keep it safe
- Store
s1kiosk-release.jksand its password in your password manager, and keep a second copy offline (an encrypted USB stick). - Never commit it.
.gitignoreignores*.jksand*.keystore, but keep it outside the repo anyway. - If it leaks, someone can sign updates your panels would accept, if they can also get them onto a panel. Rotate: make a new key, reinstall the panels by hand, and replace the secrets.
- A copy is in Bitwarden as the secure note "S1 Unleashed signing keys" (keystore, its password, and the radio bundle key), saved and checked byte for byte on 2026-11-11.
3. Add the four secrets to GitHub (once)
Secrets of the release-signing environment, not repository secrets. A repository secret can be
read by any workflow that anyone with write access pushes, on any branch; an environment secret only
by jobs that run on what the environment allows. Here that's main, test-build/** branches and the
v* and aqara-s1-plus-v* tags, and a ruleset lets only admins create those branches and tags
(see Who can sign, below).
Create the environment once (Settings → Environments → New environment → release-signing;
Deployment branches and tags → Selected: main, test-build/**, tags v*, aqara-s1-plus-v*),
then set the secrets with the GitHub CLI. These commands read the values
from the file or from a prompt, so nothing ends up in your shell history:
cd ~/secure
# The keystore, base64-encoded, from the file:
base64 < s1kiosk-release.jks | gh secret set S1_KEYSTORE_B64 --env release-signing --repo GlassworksHQ/glassworks
# Passwords: gh prompts for them ("Paste your secret"); the same password twice for PKCS12.
gh secret set S1_KEYSTORE_PASSWORD --env release-signing --repo GlassworksHQ/glassworks
gh secret set S1_KEY_PASSWORD --env release-signing --repo GlassworksHQ/glassworks
# The alias is not secret:
gh secret set S1_KEY_ALIAS --env release-signing --repo GlassworksHQ/glassworks --body s1kiosk
gh secret list --env release-signing --repo GlassworksHQ/glassworks
The workflow uses only these four secrets, the radio bundle key below, the optional VERCEL_DEPLOY_HOOK
(a Vercel deploy hook URL for the web installer), and the job's own GITHUB_TOKEN.
Who can sign
Anyone who can run a job in release-signing or radio-signing can sign code every panel accepts.
Rulesets (Settings → Rules) keep that to admins:
- Release tags (
v*,aqara-s1-plus-v*): only admins can create, move or delete them. - Test builds (
test-build/**): only admins can create, push to or delete these branches. - main: changes go through a pull request with the
app,web,scriptsandrootchecks green; no force pushes or deletion. Admins can bypass, for emergencies.
Pull requests from forks never get any secret, and no workflow uses pull_request_target or
workflow_run. Before anyone else gets admin, add yourself as a required reviewer on both
environments, so every signed build waits for an approval.
3b. The radio bundle key (once)
Only the armeabi-v7a (S1) APK carries a signed radio bundle: the root radio helper, otbr-agent/ot-ctl
and the Silicon Labs Zigbee runtime (radio.md). The other ABIs'
APKs carry none, because no S1 runs them. Panels whose boot image has the bundle
loader install it only if it is signed with the Ed25519 key whose public half is baked into the boot
image (frames/aqara-s1-plus/tools/root/s1kiosk_bundle.pub). It is a separate key from
the APK key on purpose: it lets root code run on the panel, so it lives only in ~/secure and in one
repository secret.
# Done once (2026-11-10): ~/secure/s1kiosk-radio-bundle-ed25519.pem, mode 600, never printed.
openssl genpkey -algorithm ed25519 -out ~/secure/s1kiosk-radio-bundle-ed25519.pem # OpenSSL 3
openssl pkey -in ~/secure/s1kiosk-radio-bundle-ed25519.pem -pubout -outform DER | tail -c 32 | xxd -p -c 64 \
> frames/aqara-s1-plus/tools/root/s1kiosk_bundle.pub
# The secret: an environment secret of the `radio-signing` environment (Settings -> Environments;
# create the environment first), so only the release workflow's signing job can read it:
gh secret set S1_RADIO_BUNDLE_KEY --env radio-signing --repo GlassworksHQ/glassworks \
< ~/secure/s1kiosk-radio-bundle-ed25519.pem
-
Only the workflow's
sign-bundlejob names that environment. It signs only tags whose commit is onmain(git merge-base --is-ancestor), runs no third-party action (GitHub's own checkout and download-artifact, pinned by commit SHA), and takes nothing from the unprivilegedinputsjob without checking it: the Silicon Labs runtime against the committedframes/aqara-s1-plus/tools/radio/sisdk-runtime.sha256, otbr-agent/ot-ctl againstkiln/assets.lock.json, the helper from the checkout. No required reviewer is set on the environment (one releaser); adding one later only needs the environment setting. -
Keep no repository-level
S1_RADIO_BUNDLE_KEY: other jobs would then see it. -
Back it up like the APK key. Losing it means no more radio bundle updates until panels get a boot image with a new public key (one FEL session each). If it leaks, someone who can also get a file into the kiosk's private storage could run root code: rotate it (new key, new
s1kiosk_bundle.pub, new boot image on every panel). -
The bundle version is the APK's versionCode, and panels refuse a lower one than they have, so a bundle can't be rolled back to an older (perhaps buggy) helper by replaying it.
3c. Web installer files
The installer's Vercel build downloads its binaries from pinned URLs (kiln/assets.lock.json).
The boot image's signature checker is one of them since the radio bundle loader:
frames/aqara-s1-plus/tools/root/build-verify.sh # reproducible; must print sha256 6aa0dd83…9f80 (the lock's pin)
gh release upload installer-files-3 frames/aqara-s1-plus/tools/root/out/s1kiosk_verify --repo GlassworksHQ/glassworks
(Create the installer-files-3 release first if it doesn't exist, e.g. as a copy of
installer-files-2 plus this file.) Until it is uploaded, the hosted installer's build fails at
stage-assets.mjs --remote with a download error; local builds use frames/aqara-s1-plus/tools/root/out/ directly.
4. Release
Versions are MAJOR.MINOR.PATCH, with minor and patch below 100. The versionCode is
major*10000 + minor*100 + patch, so 1.2.3 is 10203. Every release must have a higher version
than the last one. Pre-release tags (v1.2.3-rc.1) are refused by the workflow, and the app would
ignore them anyway.
ABIs
The app is built once per ABI, because each GeckoView AAR is for one ABI and carries its own classes
and omni.ja, so two cannot go into one APK. The release builds one APK for every ABI that some
frame's device runs: each frame lists its ABIs in abis in frames/<id>/design/frame.json
(frames/README.md). tools/release/frame-abis.sh prints that
list for the workflows. -Ps1Abi=<abi> (or S1_ABI) picks the ABI; without it the build is the S1's
first ABI, armeabi-v7a:
./gradlew :kiosk:assembleRelease # armeabi-v7a
./gradlew :kiosk:assembleRelease -Ps1Abi=arm64-v8a # arm64-v8a
| ABI | Release asset | Radio bundle | Who runs it |
|---|---|---|---|
armeabi-v7a |
s1-kiosk-<version>.apk |
yes | the S1 (32-bit userspace), other 32-bit devices |
arm64-v8a |
s1-kiosk-arm64-v8a-<version>.apk |
no (the bundle is the S1's root side) | arm64 tablets (generic-android), the arm64 emulator. The Mirror (Android 6) is planned: the app needs API 26, so it waits for the legacy APK (#198) |
- Every ABI's APK has the same versionCode,
major*10000 + minor*100 + patch. Store schemes put the ABI in the versionCode because a store must choose between APKs. Here the app chooses: it takes the APK of the first ABI inBuild.SUPPORTED_ABIS(the device's order of preference) that the release has (update/Releases.kt,ApkAbi). So versions go up per ABI exactly as they did before, andApkCheckstill wants the versionCode of the release's version. - The S1's asset name never changes. Apps up to 0.4.3 and the web installer only know
s1-kiosk-<version>.apk. An S1 listsarmeabi-v7a, armeabi, so it keeps taking that file. - An arm64 device that also runs 32-bit code falls back to
s1-kiosk-<version>.apkfor releases that have no arm64 APK (all releases up to 0.4.3). An arm64-only device skips them. - An ABI counts only when the release has both its APK and its
.sha256. Half a pair is skipped for the device's next ABI. - Known gap, rare. If a release ever had only
s1-kiosk-<version>.apk, an arm64 device that runs 32-bit code and has the arm64 APK installed would update to the 32-bit APK. That moves the app to slower 32-bit code until a release has an arm64 APK again.release.ymlcreates the release only after every ABI's APK is built and checked, and uploads them all in onegh release create, so a release has all of them unless an upload fails partway. Keep it that way, or make the app prefer the ABI it is running. - A device whose ABIs the app is not built for (x86_64) gets no offer, and the update entity says why.
- Adding an ABI means adding it to a frame's
abis, toApkAbi, toapk_namein both workflows if its name differs, and an upload step intest-build.yml. Gradle and the workflows' loops take the list from the frames.ApkAbiListsTestfails if the app and the frames disagree.
Tags, now that the repo will hold other frames and libraries (Glassworks). Each of them releases
under its own tag prefix, and this app's is aqara-s1-plus- (the board id it reports, since other S1
models may get their own frame). From 0.4.4 the app accepts both v1.2.3 and
aqara-s1-plus-v1.2.3 and picks its own newest release from the list, whatever else was released
after it. Apps up to 0.4.3 only read releases/latest and only understand v1.2.3, so:
- keep tagging S1 releases
v1.2.3until the repo is renamed and other frames start releasing; - an S1 release is always published with
--latest(the workflow does this), and every other frame's or library's release with--latest=false, soreleases/lateststays an S1 release for old panels.
First add a ## [1.0.0] - <date> section to CHANGELOG.md (move the
Unreleased entries into it). Its first line is what Home Assistant shows on the update card, so make
it a one-sentence summary. The release fails early if the section is missing.
git switch main && git pull
git tag -a v1.0.0 -m "S1 Kiosk 1.0.0"
git push origin v1.0.0
gh run watch --repo GlassworksHQ/glassworks # or the Actions tab
The workflow then:
- checks the tag;
- builds the Silicon Labs runtime (
inputsjob:frames/aqara-s1-plus/tools/radio/build-sisdk-runtime.sh, Docker, a pinned image and Ubuntu snapshot; it must reproduceframes/aqara-s1-plus/tools/radio/sisdk-runtime.sha256; never Silicon Labs' zigbeed itself), then signs the radio bundle in thesign-bundlejob (environmentradio-signing, main only, every input checked against committed hashes;frames/aqara-s1-plus/tools/radio/make-bundle.py --app-version, version = the versionCode, checked againstframes/aqara-s1-plus/tools/root/s1kiosk_bundle.pub). PR CI catches most drift before a tag does. Thesizejob inpr.ymlcaches the runtime under a key made from the script,frames/aqara-s1-plus/tools/radio/sisdk/and the hash file. When one of them changes, it rebuilds from scratch and checks the hashes. On a cache hit, it only checks the cached files against the hashes. So drift outside the repo (the Ubuntu snapshot, the cpc-daemon tag) still shows first in this fresh release build; - builds
:kiosk:assembleReleasewithS1_VERSION=1.0.0once per ABI, thearmeabi-v7aone with the bundle as APK assets. The build fails if a key is missing (S1_REQUIRE_RELEASE_SIGNING=true); - runs
apksigner verify --print-certson each APK, so the certificate fingerprint is in the log, checks the package name, version and native code ABI, that the signed bundle is in thearmeabi-v7aAPK and not in the others, and that no zigbeed is anywhere; - writes a
.sha256for each; - creates the release, with that version's CHANGELOG.md section as the notes. The bundle is not published on its own (its Silicon Labs libcpc may only be distributed inside the product).
- asks Vercel to rebuild the web installer, so it installs the new release (
VERCEL_DEPLOY_HOOK).
HA shows the first 255 characters of the notes, with a link to the full release.
Panels see the release within 24 hours. To check right away, call homeassistant.update_entity
on update.s1_panel_app_update: HA sends the entity's "check" command.
Panels on 0.4.0 or older can't install it from HA. Their update path refused every release as
"the APK is not signed": on Android 10, getPackageArchiveInfo with only GET_SIGNING_CERTIFICATES
returns no signer for a downloaded APK. 0.4.1 also asks for GET_SIGNATURES
(esphome.md). Because the bug is in the version doing the installing, those
panels need one manual update to 0.4.1 or later (the web installer's Already installed? Finish setting
it up, or adb install -r, see install.md); from then on HA installs work.
The hosted web installer installs the latest release it saw when it was last built
(kiln/scripts/stage-assets.mjs). The workflow's last step asks Vercel to rebuild it through the
VERCEL_DEPLOY_HOOK secret; without that secret it only warns, and you redeploy the installer by hand.
Vercel does not build on pushes (git.deploymentEnabled: false in kiln/vercel.json), so PRs get no
Vercel preview. Production builds come only from that deploy hook, called by release.yml and by
installer-deploy.yml. The second runs on a push to
main that changes an installer input (kiln/, branding/, or a repo file the installer stages), or
by hand from the Actions tab.
Raising targetSdk
targetSdk is in frames/aqara-s1-plus/android/build.gradle.kts, and only there. It opts the app
into newer Android rules on newer devices. It doesn't change which devices can install the app:
minSdk (26) decides that.
Raise it once a year, when a new Android version comes out. Generic Android devices on Android 12+ install updates without a tap only if the new APK targets a recent enough API, and each Android version raises that bar by one level (Android 17 needs 35; frames/generic-android).
- Read Android's "behaviour changes for apps targeting" page for the new level, and note in the PR which items apply to the app and how each is handled.
- Raise
targetSdkby one, in its own PR. - Check it on the newest device we have (today the Pixel Tablet): the setup screen, the settings, the overlays and the dashboard are not under the system bars, the foreground service starts after a reboot, and an update from HA installs without a tap. Before/after screenshots go in the PR.
tools/release/check-update-compat.shmust still pass: the target doesn't touch applicationId, signing or versionCode.
| Date | targetSdk | Why | PR |
|---|---|---|---|
| 2026-11-15 | 34 → 35 | Android 17 (the Pixel Tablet) installs updates without a tap | #277 |
The secret store and downgrades
Since the secret store (2026-11-15, secrets.md), the app seals its secrets with a key in
the Android Keystore. An update seals them in place and keeps every one. A downgrade doesn't: a
build from before the secret store reads a sealed value as a broken one. The panel then needs setting
up again: the Home Assistant sign-in (QR code), the ESPHome API key, the Sendspin pairing and the
camera password. main isn't a release, so this only matters when you install an older test build
over a newer one. Don't add a path that writes plaintext back for older builds.
Building a signed APK locally
The same environment variables as CI. Without them, assembleRelease produces an unsigned APK
(kiosk-release-unsigned.apk); it never falls back to the debug key.
export S1_KEYSTORE_FILE=~/secure/s1kiosk-release.jks S1_KEY_ALIAS=s1kiosk S1_VERSION=1.0.0
read -rs S1_KEYSTORE_PASSWORD && export S1_KEYSTORE_PASSWORD S1_KEY_PASSWORD="$S1_KEYSTORE_PASSWORD"
./gradlew :kiosk:assembleRelease
If only some of the four variables are set, the build stops and names the missing ones.
Signed test builds of a branch
To try a branch on a panel that runs a release, without losing the app's data, let CI sign it:
git push origin HEAD:test-build/<name> # builds as the latest release's version
git push origin HEAD:test-build/v1.2.3/<name> # builds as 1.2.3 (panel on an unreleased version)
gh run download <run-id> -n s1-kiosk-test-<sha> # armeabi-v7a, for the S1
adb install -r s1-kiosk-test-*.apk
gh run download <run-id> -n s1-kiosk-test-arm64-v8a-<sha> # arm64-v8a, its own artifact
test-build.yml runs the unit tests and builds the release
variant with the release key, once per ABI. It takes the latest release's version, or the one in the branch name
(Android refuses to install a lower versionCode, so a panel on an unreleased version needs that). The
APK then installs over the panel's app, HA's update entity offers nothing, and the next real release
replaces it. The build also gets its commit (S1_TEST_BUILD, a BuildConfig field): the Manage page
and the settings' About say "0.4.3 · test build 28c157d", while versionName and versionCode stay the
release's. It carries no
radio bundle, so the panel's root side stays as it is. The artifact is kept for 3 days, and since
the repo is public, any signed-in GitHub user can download it. To go back to the release, install
its APK from the release page with adb install -r. Delete the test-build/ branch when you're
done.
Debug builds and the release key
assembleDebug is unchanged: version 0.1.0 (versionCode 1), signed with the local debug key.
A panel running a debug build cannot update to a release through HA, because the keys differ.
The update entity then says so ("signed with a different key than this app"). Moving such a panel
to releases takes a one-time reinstall: uninstall the debug app, then install the release APK.
Both installers do that for you, after asking, and keep the panel on its Wi-Fi. The app's data is
kept only where adb has root; on a normal panel the switch resets the app's settings (sign-in,
pairing key, options). See install.md.
Libraries
The libraries in libs/ go to Maven Central as dev.glassworks:<name> (#153): esphome-api (a jar),
esphome-api-android, improv, sendspin and voice (AARs). sendspin and voice (#152) are set up
but have no release yet. Each has its own semver version, in version= in
libs/<name>/gradle.properties, and its own libs/<name>/CHANGELOG.md, apart from the app's. Each
release ships the jar or AAR, a sources jar, a KDoc jar (Dokka), the POM (MIT, the GlassworksHQ org as
developer) and a .asc signature for each. The licence is in the jar as META-INF/LICENSE. Their
dependencies come from Maven Central with their own licences.
Ported code keeps its own licence. voice's MicroFrontend.kt is a port of TensorFlow Lite Micro's
audio frontend (Apache-2.0) and kissfft (BSD-3-Clause). A library lists such licences in its
gradle.properties as extraLicenses=<SPDX id>|<upstream copyright line>;…, and explains the port in
libs/<name>/NOTICE. The build then adds each licence to the POM, and ships it in the jar as
META-INF/LICENSE-<ID> (from LICENSES/<id>.txt, under the copyright line), with META-INF/NOTICE.
check-lib-artifact.sh checks both. They're built for Kotlin 2.1 with kotlin-stdlib 2.1, so apps on Kotlin 2.0 or newer can
use them.
bluetooth-proxy isn't published yet. It's alpha, and GATT connections will change its API. To publish
a library, apply id("org.jetbrains.dokka") and id("com.vanniktech.maven.publish") in its build file,
and give it a gradle.properties with version and description and a CHANGELOG.md. The rest of
the setup is in the root build.gradle.kts.
A release can't be deleted from Maven Central, and its version can't be used again.
The public API
Each library's public API is dumped in libs/<name>/api/<name>.api: every public class and member,
as apps compile against it. ./gradlew apiCheck fails when the code's API differs from the dump. It
is part of check, and libs-publish in pr.yml runs it. When you change the API on purpose,
update the dump with:
./gradlew apiDump # or :esphome-api:apiDump for one library
Commit the dump with the change. Its diff is the API change a reviewer reads. A removed or changed line breaks apps built against an older release, so it needs a new minor version while the version starts with 0, and a new major version from 1.0.
The rest of the API rules, all in the root build.gradle.kts:
- Explicit API mode (strict). Every public declaration says
public. Make anything elseinternal: once released, a public declaration can't be taken back without breaking someone. - KDoc on every public declaration. The KDoc jar (Dokka) fails to build when one has none.
- README examples compile. Each
```kotlinblock of a library's README must be in itsReadmeExample*test, line for line (readmeSnippets, whichtestruns). Gradle blocks are skipped.
The dump comes from the binary-compatibility-validator's tasks, wired by hand. Neither Kotlin's own
abiValidation nor that plugin finds the classes of an Android library on AGP 9's built-in Kotlin
(KT-78025): both write an empty dump.
Cut a release
The tag is libs/<name>/v<MAJOR.MINOR.PATCH>. It must match version in that library's
gradle.properties. release.yml takes only v* and aqara-s1-plus-v* tags, and the app's update
check skips any other tag (Releases.tagVersion). So a library tag never makes an app release.
-
In a PR: set
versioninlibs/<name>/gradle.properties, and rename## [Unreleased]inlibs/<name>/CHANGELOG.mdto## [<version>] - <date>. Merge it. -
Tag the merged commit on
mainand push the tag:git fetch origin git tag libs/esphome-api/v0.1.0 origin/main git push origin libs/esphome-api/v0.1.0 -
libs-release.ymluploads the release (below). WhileMANUAL_PUBLISHis'true'(it must be exactly'true'or'false'; the job fails on anything else), open Deployments on the Central Portal, check the files, and press Publish. It's on Maven Central 10 to 30 minutes later. -
Once the Portal shows the deployment as Published, publish the draft GitHub release that the workflow made:
gh release edit libs/esphome-api/v0.1.0 --draft=false --latest=false. If you publish it from GitHub's web page instead, untick "Set as the latest release": panels on 0.4.3 readreleases/latest, which must stay the S1 app's release.
Release esphome-api before esphome-api-android, sendspin and voice: the workflow refuses a library whose
dev.glassworks dependency isn't on Maven Central yet. Once a few releases have gone out cleanly,
set MANUAL_PUBLISH: 'false'. The workflow then publishes the deployment itself and makes the
GitHub release public.
What the workflow does
The job runs in the maven-central environment, which deploys only from libs/*/v* tags.
- Reads the library and version from the tag. It stops if the library doesn't apply the publish
plugin, if the version isn't
versionin itsgradle.properties, if the commit isn't onmain, or ifCHANGELOG.mdhas no section for it. - Runs the library's tests (
./gradlew :<name>:test). - Publishes it to mavenLocal unsigned and checks the files with
tools/release/check-lib-artifact.sh: the jar or AAR, sources, KDoc, POM and licence, and no class under the oldsh.edmpackages. - Signs it and uploads it to the Central Portal (
publishToMavenCentral). It then polls the Portal for up to 60 minutes until the deployment is validated, and fails if the Portal refuses it. (The plugin validates only deployments it publishes itself.) - Makes the GitHub release
<name> <version>, with the changelog section as notes and--latest=false, soreleases/lateststays the S1 app's release.
Every PR that touches libs/, the Gradle build or these scripts runs a dry run (libs-publish in
pr.yml). It needs no secrets, so it runs on forks too:
./gradlew publishToMavenLocal # no key: unsigned
tools/release/check-lib-artifact.sh esphome-api # and esphome-api-android, improv, sendspin, voice
tools/release/lib-consumer-check.sh # fresh apps build against them (below)
lib-consumer-check.sh builds two minSdk 23 Android apps, at compileSdk 37.2 and at compileSdk 23
(the AARs' minCompileSdk), and a JVM app on Kotlin 2.0.21, the oldest Kotlin the READMEs promise. It
needs the android-23 and android-37.2 SDK platforms.
If the validation wait times out
The bundle is already on the Portal when the 60-minute wait gives up. Don't re-run the workflow: it would upload the same version again, and the Portal rejects a duplicate. Instead:
Open Deployments and look at the deployment.
- Failed: drop it there, and make no GitHub release. A version is used up only once it's published. Fix the cause, and if that needs a new commit, release it as the next patch version.
- Validated (or still validating: wait until it is):
-
Press Publish, and wait until the Portal shows the deployment as Published. If it shows it as failed instead, follow the failed case above.
-
Make the GitHub release by hand, as the workflow's last step would (here for esphome-api 0.1.0):
{ printf 'Maven Central: `dev.glassworks:%s:%s`\n\n' esphome-api 0.1.0 tools/release/changelog-section.sh 0.1.0 libs/esphome-api/CHANGELOG.md; } > /tmp/notes.md gh release create libs/esphome-api/v0.1.0 --verify-tag --latest=false \ --title "esphome-api 0.1.0" --notes-file /tmp/notes.md
-
Rotate the token or the signing key
The secrets are in the maven-central environment (Settings → Environments, or
gh secret set <NAME> --env maven-central):
| Secret | What |
|---|---|
MAVEN_CENTRAL_USERNAME, MAVEN_CENTRAL_PASSWORD |
A Central Portal user token (not the login) |
SIGNING_IN_MEMORY_KEY |
The ASCII-armoured private signing key (gpg --export-secret-keys --armor <id>) |
SIGNING_IN_MEMORY_KEY_PASSWORD |
Its passphrase |
SIGNING_IN_MEMORY_KEY_ID |
The last 8 hex digits of its fingerprint |
- The token. On the Portal, open Account → Generate User Token. Set both secrets to the new pair, then revoke the old token there.
- The signing key. Make a new RSA-4096 key and upload its public key to keys.openpgp.org and
keyserver.ubuntu.com. The Portal checks signatures against those servers. Set the three
SIGNING_*secrets. Leave the old public key on the servers, so older releases still verify. If the old key leaked, publish its revocation certificate too. - No dry run tests the secrets; the next release tag does. The workflow checks that all five are set before it builds.