This is the public version of the release procedure. It exists for two readers: a contributor who
wants to know what happens between "merged" and "the image updated on my NAS", and whoever cuts the
first release of a fork under the clause in CONTRIBUTING.md
("If the maintainer stops"). Nothing here needs tooling outside this repository: git, npm,
gh and a browser are enough.
A release is a tag vX.Y.Z on this repository. Everything downstream hangs on that tag:
docker-publish.ymlruns on everyv*tag, from any branch, and pushes the multi-arch image toghcr.io/ulsklyc/yuvomiand to the legacy mirrorghcr.io/ulsklyc/oikos(the mirror must stay: installations from before the rename pull it and are updated through it).release-assets.ymlis started by hand right after the GitHub release was created as a draft (GitHub runs no workflow for a draft'screatedevent, so there is no automatic trigger that fires before the release is public). It packs the tag intoyuvomi-X.Y.Z-dist.tar.gz: thegit archivetree of the tag plus the built web appdist/(withdist/THIRD-PARTY-NOTICES.txt), under the one top-level folderyuvomi-X.Y.Z/. The source stays in the tarball because the server imports shared code frompublic/utils/and readspublic/locales/. Before packing, the build runs twice more in fresh directories and the results are compared, and the pack itself is reproducible (sorted entries, owner 0, the tagged commit's mtime,gzip -n). The job then writesSHA256SUMS, attests both with a build provenance attestation, uploads them and only then publishes the release. YunoHost and the Proxmox script install from that asset: they strip the one folder, runnpm ci --omit=devon Node 24 and startnode server/index.js, with no build step of their own. Neither sees a draft, so no channel ever sees a release without its tarball. If the job fails or was never started, the release stays a draft; start it withgh workflow run release-assets.yml --ref vX.Y.Z -f tag=vX.Y.Z.umbrel-publish.ymlruns when the GitHub release is published and opens, or renames, the store PR againstgetumbrel/umbrel-apps. A release thatrelease-assets.ymlpublishes with the workflow token fires nopublishedrun of its own, so that job starts this one explicitly.- TrueNAS picks up the new image tag on its own; the Unraid template points at
latest. - Three packages live in repositories of their own and follow the release without a trigger
from here. The Home Assistant app (
ulsklyc/yuvomi-home-assistant) builds on the image: a Renovate pull request moves itsFROMtag once the image exists, and after the merge that repository builds its own per-architecture images. The YunoHost package (ulsklyc/yuvomi_ynh) opens a daily bump pull request with the asset URL and its checksum, taken only aftergh attestation verifypassed. The iOS app (ulsklyc/yuvomi-ios) reads the OpenAPI document of the newest release once a day, from the tag's source tree: it loadsserver/openapi.jswith nothing installed, so that file and what it imports must not neednode_modules.
These packages address a few things here by name: the entry point node server/index.js, the
start-up log line Server running on port, GET /health, POST /api/v1/auth/setup, and the
asset name yuvomi-*-dist.tar.gz. Renaming or moving one of them is a change to those
repositories too, and nothing in this repository's tests goes red for it.
The in-app changelog reads the GitHub release, not CHANGELOG.md, so a release without notes is
visible to every household on the next start.
Releases run on two tracks, described in CONTRIBUTING.md:
anything under public/pages, public/styles, public/utils, public/components or
public/settings ships on Wednesdays and Sundays only; everything else ships any day, at most once
per calendar day. npm run check:release-cadence decides, and it runs before the tag, because it compares
git describe --tags with HEAD and an already-set tag makes that diff empty. It judges the whole
release, not the last commit: a server-only fix on a main that also carries interface work since
the last tag is an interface release.
-
Version.
npm version <patch|minor|major> --no-git-tag-version, then read the new number frompackage.json. The bump comes before the changelog:test:changelogaccepts a version heading that has no tag yet only when it equals the version inpackage.json, so that an ordinary pull request cannot file its entry under a release heading of its own. -
Changelog. Rename
## [Unreleased]to## [X.Y.Z] - YYYY-MM-DD, add a fresh empty## [Unreleased]above it, keep every bullet. Only Keep-a-Changelog sections (Added,Changed,Fixed,Removed,Security), one bullet per user-facing change, in English. Do not touch the file header;npm run test:changelogchecks the structure, and that no section released earlier differs from its tag. -
Service worker. Nothing to set by hand any more:
npm run buildwritesAPP_RELEASEfrompackage.json, the build revision and the precache list intodist/sw.js(scripts/build/service-worker.ts). If a file was added underpublic/,test:static-copy-listandtest:sw-precachehave to be green: a file the module graph does not reach must be on the copy list inscripts/build/static-files.ts. -
Version literals in the docs. The landing pages and the installation guide carry the version and the release date as text:
docs/index.html(hero bar and footer, withdata-released),docs/install.html(footer, withdata-released), anddocs/installation.md(pinning example, compose line,cosign verifyandimagetools inspectexamples, sample startup log). Both footers carry the date twice, indata-releasedand as visible text, and the version grep finds neither. Treat that list as a hint and the grep as the authority - it has been wrong twice:grep -rn "<old version>" README.md README.de.md docs/*.html docs/*.md tools/installer/
Historical
(vX.Y.Z)markers insidedocs/SPEC.mdstay as they are. -
Star count on the landing pages.
node scripts/update-gh-stars.mjs, then stagedocs/index.htmlanddocs/install.htmlif it changed anything. Both carry the number in[data-gh-stars]elements and the script writes both - staging onlyindex.htmlleavesinstall.htmlbehind at the old count. It is embedded here, at release time, on purpose: the page never callsapi.github.comfrom a visitor's browser, so opening it transmits no visitor data to a third country (docs/datenschutz.html). A weekly workflow did this until 7 September 2026. It was removed becausemainrequires status checks that a push from Actions cannot bring: the push was rejected, and the count silently stopped moving after 24 August. -
Umbrel store notes. Fill
.github/umbrel-release-notes.mdand move its<!-- version: X.Y.Z -->marker. The publish workflow takes the text verbatim and aborts if the marker does not match the release, which is deliberate: a stale note describes an update a household is not getting. The rules for the text are in the head of the file. -
Cadence.
npm run check:release-cadence. Red is an answer, not an obstacle: wait for the next Wednesday or Sunday, take the interface change out, or - for a security or data-loss fix that cannot be separated frommain- pass--hotfix "<reason>"; the reason is mandatory and printed. A foundation release of the architecture roadmap (build, runtime and rules, no feature interface) passes--foundation "<phase>"instead, for example--foundation "1a toolchain"; it is allowed on any day and printsFundament-Release <phase>. A foundation release is announced one release ahead (a paragraph under the previous release block and an Announcements discussion), its CHANGELOG block starts with### Foundation, and before its tag the way back is tried once: the previous image and the foundation build run in turn on a copy of the same database (the demo seed does), a backup made on the new build restores on the previous one, and the service worker switches both ways without an error screen.scripts/rollback-probe/run.sh <previous-image> <new-image>runs exactly that (Docker, curl andnpm ciin the checkout; it prints a protocol per stage and keeps fingerprints, API snapshots and screenshots in its work directory). The result goes into the release notes. The foundation does not change the database, so an operator can pin the previous tag (installation.md, "Pinning a version"). -
Handrail, interface releases only. If the diff since the last tag touches the interface paths above, run the browser suite once, and read its exit code from a file rather than a pipe (
| tailreports the status oftail):npm run test:document-guards > /tmp/dg.log 2>&1; echo $?
-
The whole chain.
npm test, green. A green single suite is not evidence; the guards that went red in the past (test:sw-precache,test:document-folder-keys,test:changelog) were never in anyone's "relevant" list. -
Commit, fetch, tag, push - in that order.
git commit -m "chore: release vX.Y.Z"withCHANGELOG.md,package.json,package-lock.json, the docs from steps 4 and 5 and the Umbrel notes staged by name (nevergit add -A). Thengit fetch originbeforegit tag vX.Y.Z: the fetch brings in a tag somebody else may have set for the same version, and the tag command fails before anything is pushed. Thengit push && git push --tags. -
GitHub release, as a draft. Write the new changelog block to a file and pass it with
--notes-file; a failed shell substitution yields an empty string thatghaccepts without a word. Create the release with--draft, read the body back (a successfulcreatereports the URL either way), then start the asset job, which publishes the release once the tarball is on it:gh release create vX.Y.Z --repo ulsklyc/yuvomi --title "vX.Y.Z" --notes-file <file> --draft gh release view vX.Y.Z --repo ulsklyc/yuvomi --json body --jq .body gh workflow run release-assets.yml --repo ulsklyc/yuvomi --ref vX.Y.Z -f tag=vX.Y.Z
The job runs at the tag (
--ref vX.Y.Z), not atmain, and refuses any other ref: the attestation names the ref and commit the run sits on, and an operator checking--source-ref refs/tags/vX.Y.Zmust find the tag there. A patch release from a branch works the same way, as long as its tag containsrelease-assets.yml.Wait for the job and check that the release came out of draft with both files on it:
gh run list --repo ulsklyc/yuvomi --workflow=release-assets.yml --limit 1 gh run watch <run-id> --repo ulsklyc/yuvomi --exit-status gh release view vX.Y.Z --repo ulsklyc/yuvomi --json assets,isDraft
Expected:
isDraft: false, assetsyuvomi-X.Y.Z-dist.tar.gzandSHA256SUMS. A release that is still a draft is invisible to every channel; fix the cause and start the job again with the same command. Never publish the draft by hand to get past it. -
Downstream.
gh run list --workflow=docker-publish.yml --limit 1must show success (a failed image build silently stalls TrueNAS too). Check the tarball the way an operator would, from an empty directory:gh release download vX.Y.Z --repo ulsklyc/yuvomi --pattern 'yuvomi-*-dist.tar.gz' --pattern SHA256SUMS sha256sum -c SHA256SUMS gh attestation verify yuvomi-X.Y.Z-dist.tar.gz -R ulsklyc/yuvomiYunoHost's daily bump PR (
ulsklyc/yuvomi_ynh) and the Proxmox script pick the asset up from there. The asset job also startscorpus.yml, which attachesyuvomi-X.Y.Z-corpus.db(plus.sha256) when the release changes the database schema or is a foundation release; check it withgh run list --repo ulsklyc/yuvomi --workflow=corpus.yml --limit 1. A red run does not touch the release; the restore drill names the missing database. Then look the Umbrel PR up rather than assuming a number - the workflow renames the open PR if there is one and opens a new one only once the previous one was merged:gh pr list --repo getumbrel/umbrel-apps --author ulsklyc --state all --limit 5
Since v2.64.1 (4 September 2026) a security fix does not wait for main to be releasable and
does not pull the interface work waiting there forward with it. It ships from a branch off the
last tag, carrying the fix, its tests and its documentation and nothing else:
git switch -c release/X.Y.Z vX.Y.(Z-1)- the branch starts at the tag, not atmain.- Cherry-pick the fix commits. On the branch
## [Unreleased]holds only the### Securityblock; expect a conflict there ifmain's Unreleased section is not empty, and resolve it to the security entries alone. - Steps 1 to 6 above, by hand where the version bump tooling assumes
main. The Umbrel notes are part of it: the publish workflow aborts on a stale version marker whichever branch the release came from. A guard that landed after the tag (the cadence check itself was such a case in September 2026) is absent on the branch; run it from a copy taken offmain. npm teston the branch, then commit, fetch, tag, push, release, downstream - steps 9 to 12. The cadence check passes on the second track by construction: the diff since the last tag is the fix.- Merge the branch back:
git switch main && git merge --no-ff release/X.Y.Z. One conflict is normal -CHANGELOG.md, where the new block goes below## [Unreleased]and the Unreleased bullets stay. A branch off a tag before 2.88.0 also conflicts inpublic/sw.js, which carried the version by hand until then;main's shape of the file wins. After resolving, check thatCHANGELOG.mdcontains no conflict markers and that its heading structure is what you meant (git addchecks neither;test:changelogcompares every released section with the new tag and so catches a bullet that slid into or out of the new block, but not one that landed under the wrong heading inside[Unreleased]), runnpm teston the merge, push.
Publish the advisory after the image is out, with the fixed version, the reporter's credit and a CVE requested through GitHub. The response times this has to fit are in SECURITY.md.
- The image names in
docker-publish.ymlfollowgithub.repositoryandgithub.repository_owner, so a fork publishes under its own account without edits; theoikosmirror line then publishes<owner>/oikos, which a fork can drop. umbrel-publish.ymlneeds theUMBREL_FORK_TOKENsecret (a classic token with thepublic_reposcope and nothing else; a fine-grained token cannot open the pull request ingetumbrel/umbrel-apps) and pushes to a fork of that repository; without the secret the job fails and nothing else is affected. Only its last job,publish, sees the token: the catalog's linter and its npm dependencies run in a job of their own with no secret and no rights. A manual run with-f dry_run=trueprepares and lints without pushing.release-assets.ymlneeds no secret: the workflow token uploads the assets, and the attestation is signed through GitHub's OIDC token and Sigstore. Attestations are free for public repositories only; a private fork has to drop that step.- The Claude review workflows need their own API key or can be deleted; they merge nothing.
- The image runs Node 24 (
Dockerfile, pinned to a digest that Dependabot moves), and CI tests Node 24 and 26;test:docker-publishkeeps the CI matrix and the image's major together. - Every action in
.github/workflows/is pinned to a commit SHA with the version as a comment;test:workflow-pinsrefuses a floating tag, and Dependabot updates the SHA and the comment together.