Releases and upgrades
On this page
Mob publishes two channels from main, and a database is upgraded only within a
migration window, so old schema code does not stay in the tree forever.
Versions
Section titled “Versions”- A nightly build is named
{date}.{sha}: the UTC date of its commit and the commit’s short hash, e.g.20261011.c0502b6. The release workflow passes it toscripts/release.ts, which compiles it into the binary. - A stable build reports its
vX.Y.Ztag the same way. A build made without a version, such asbun run build:cli, and a run from source reportdev. mob --versionandGET /api/runtimeshow the version.
Channels
Section titled “Channels”.github/workflows/release.yml runs once CI passes on a commit pushed to
main:
- nightly: any other commit is published as a prerelease tagged
{date}.{sha}(titledMob {date}.{sha} (nightly)), never marked as the latest release. Nightly releases may be pruned. - stable: release-please
keeps one release PR (
chore(main): release X.Y.Z) open, updating.release-please-manifest.json("X.Y.Z") andCHANGELOG.mdbuilt from thetype(scope):commit messages, which are the titles of the squash-merged pull requests. Merging it and passing CI creates thevX.Y.Ztag and GitHub release, which becomes the latest one instead of a nightly.
Stable releases start at v0.1.0. Below 1.0, a feat raises the minor version,
a fix, perf or revert the patch version, and a breaking change (! or
BREAKING CHANGE:) the minor version. feat, fix, perf and revert
appear in the changelog; other commit types are left out.
Builds
Section titled “Builds”scripts/release.tsbuilds both channels with the web UI embedded, usingbun build --compilefrom one Linux runner: archives for Linux (amd64, arm64, each for glibc and for musl), macOS (amd64, arm64) and Windows (amd64), plusSHA256SUMS. A musl build tells OpenTUI to load its musl library (OPENTUI_LIBC, set at build time). The release job installs every platform’s native packages (bun install --frozen-lockfile --os='*' --cpu='*' --libc='*') so each target finds them. Thedesktopjob packages thosemobbinaries into Electron installers for Linux (x64,arm64), macOS (x64,arm64) and Windows (x64) with the same SemVer version as npm, andchecksumsupdatesSHA256SUMSto include them (see Desktop app).- Both channels attest their CLI archives and desktop installers with
actions/attest-build-provenance, verified withgh attestation verify. - With
--npm,scripts/release.tsalso writes the npm packages todist/npm, andscripts/npm/publish.tspublishes them with provenance once the GitHub release exists.usemobholds themoblauncher (scripts/npm/mob.js) and lists one@usemob/OS-ARCHpackage per binary (@usemob/linux-x64-muslfor musl) as an optional dependency. Theiros,cpuand, on Linux,libcfields let npm and Bun install only the one for the machine;scripts/npm/platform.jsfinds it the same way. On Linux and macOS the package’s postinstall (scripts/npm/install.js) hard links that binary over the launcher, so the command runs natively; on Windows, or when install scripts are skipped, the launcher runs the binary with Node.js. A stablevX.Y.Zis published asX.Y.Zunder thelatesttag. A nightly is published under thenightlytag as a prerelease of the next minor version from.release-please-manifest.json, ordered by UTC commit time, e.g.0.5.0-nightly.20261117133514.g20fac4c. Installing them is described in Install. - An experimental workflow reports how much of the host
scriptc can compile natively, after
host changes reach
mainand weekly. It never blocks a merge, and no release contains a scriptc build.
Repository setup: on npmjs.com, each package (usemob and every
@usemob/*) names fdkevin0/mob’s release.yml as its trusted publisher, so
the workflow publishes without a long-lived token. Its “Allowed actions” must
include npm publish: npm allows only npm stage publish by default, and once
a trusted publisher exists npm signs in with it in place of NPM_TOKEN, so a
stage-only publisher fails every release with “403 OIDC permission denied for
this action”. An NPM_TOKEN secret, a
granular token for usemob and the @usemob scope, covers packages that have
no trusted publisher yet, such as a new platform’s first release (without
either, the packages are built but not published); a
RELEASE_PLEASE_TOKEN secret so the release PR starts CI; and GitHub Actions
allowed to create pull requests.
Database upgrades
Section titled “Database upgrades”-
PRAGMA user_versionholds the schema. Themetatable’sservice_versionholds the release that last opened the database, so a refusal can name it. -
packages/core/src/chat/schema.tsholds the current schema and, by version, the statements that bring the one before it up to date. Opening a database:- empty: create the current schema;
- schema 10 or newer: apply the remaining upgrades and the current schema in one transaction;
- older than 10: refuse, and ask the user to start a Go release of Mob once to upgrade it;
- newer than this code: refuse and ask for the release recorded in
meta, or a newer one.
A refused database is not changed. The desktop app shows the message in its window; the CLI prints it.
-
An upgrade stays in the code for at least six months after it was written. To retire older ones, raise the oldest schema
openaccepts and name, in its refusal, the last release that still upgrades from there.