ci(release)!: release through Changesets with an alpha prerelease channel - #2430

What this changes

Releases now go through Changesets, ported from Fiestaboard/FiestaUI#375. Every merge to main that touched code used to cut a release. Now:

1. Shipped PRs add a changeset. Run npx changeset, pick patch/minor/major, and write one user-facing line. CI's new Release guards job (part of CI Success) fails a PR that changes shipped files without one.
2. Release keeps one Version PR open. On every push to main/alpha, the Release workflow runs changesets/action@v2 and maintains a single "chore: release" Version PR. That PR bumps package.json, both lockfiles, web/package.json and src/__init__.py, and writes CHANGELOG.md.
3. Merging the Version PR releases. The workflow builds the multi-arch image from that commit and pushes the manifest. After that it creates the tag and the GitHub Release, so installs are never offered an image they can't pull. On stable it then dispatches the FiestaPi build, the docs snapshot and the Docker Hub description.

There are two channels. main releases X.Y.Z to :latest. alpha is a long-lived branch in pre mode with tag beta. It releases X.Y.Z-beta.N to :beta as a GitHub prerelease, which only beta-channel installs see. Both names were confirmed with the maintainer.

Design and lifecycle: docs/internal/development/RELEASING.md. Plan: docs/internal/plans/2026-11-07-changesets-release.md.

Key decisions

• No publish script. Nothing goes to npm. scripts/release/plan.py releases when package.json's version has no GitHub Release yet. Re-runs after a failed build resume, and the action's "empty changesets" no-op can't strand a release.
  • Builds use the commit that set the version, not the branch tip.
  • plan.py refuses to cut a prerelease from main or a stable release from alpha.
  • It also refuses any version that doesn't sort above the newest stable release. Otherwise beta installs would ignore the beta and fall back to stable (feat(update): a beta install graduates onto the release once it overtakes #1992).
• Trigger is push on [main, alpha], with no path filters. Concurrency is per branch and never cancels. Version PRs are opened with the Claude bot app token, so their CI isn't held in action_required.
• Pre-mode guards (scripts/release/pre_mode.py):
  • A PR into main can't bring pre mode; exit mode is allowed, because that's the promotion.
  • A PR into alpha must keep the beta pre tag.
  • The Release workflow skips on alpha in exit mode and fails without pre.json.
• Changeset check (scripts/release/changeset_check.py):
  • "Shipped" is an allowlist mirroring the Dockerfile's COPY sources plus pi-image/. A test parses the Dockerfile so a new COPY can't slip past.
  • fiestaupdater/, tests, Markdown, docs and CI don't need a changeset. This keeps the feat(fiestaupdater): install a named tag, so a box can change channel #1969 lesson.
  • Waived by an empty changeset, by the no-changeset label (read live, so a re-run picks it up), or by head refs changeset-release/*, main (syncs), alpha (promotion) and dependabot/*. Dependency bumps ride along with the next release.
• Pi image is dispatched, not chained. build-fiestapi.yml no longer listens for the release workflow's completion, because most runs only update the Version PR. It takes a release_tag input and builds from that tag.

Removed

• release-beta.yml and its tests.
• From release.yml:
  • the label-driven bump;
  • the chore: bump version push to main with RELEASE_PAT;
  • revert-on-failure, which force-pushed main.
• The bump-label step in pr-label.yml. Area labels stay.
• The version buckets in .github/release.yml.
• The bump modes of version-sync.js. It now only syncs, and it accepts prerelease versions, which are now committed.
• RELEASE_CHANNELS.md, replaced by RELEASING.md.
• next in CodeQL, replaced by alpha.

Behaviour changes worth knowing:

• The daily plugin-previews.json push from Scheduled: Maintenance no longer cuts a patch release. It rides along with the next one.
• The release workflow is now named "Release".

Also fixes: E2E image check on Docker 29

E2E has failed on every PR that builds the test image since Nov 6, fiestaui-upgrade included, with "Loaded image does not match the producer's image ID".

• Cause: ubuntu-latest moved to ubuntu-26.04, which brings Docker 29. Docker 29 defaults to the containerd image store, where docker image inspect .Id after docker load is the image's manifest digest. The old check compared it against buildx's imageid, which is the config digest.
• Fix: build-test-image now also exports digest, and both E2E jobs accept either of this run's two identities and nothing else.
• Checks: reproduced and verified in docker:29-dind (containerd store): real digests are accepted, wrong or missing ones rejected. tests/ci/test_image_handoff.py covers both stores.

Downstream

FiestaUI's upgrade PRs (fiestaui-upgrade) change web/package*.json, which is shipped. They are deliberately not exempt. The companion PR makes them carry .changeset/fiestaui-upgrade.md: Fiestaboard/FiestaUI#376. It's a no-op for repos without .changeset/, so the two PRs can merge in either order. Until it lands, an open upgrade PR needs a changeset (or the label) added by hand. claude-issue-triage.yml and CLAUDE.md tell Claude to write changesets.

Verification

• pytest: the new tests/test_release_guards.py and tests/test_release_workflow.py, plus the 24 existing test files that read workflows, versions or package files (846 tests in all). All pass.
• ruff check/ruff format, npm run docs:lint and actionlint report nothing new. The only actionlint findings are in older steps.
• Simulated npm run version-packages in a scratch clone:
  • stable: 10.3.2 → 10.4.0, with all five version files and CHANGELOG.md;
  • pre: pre enter beta → 10.4.0-beta.0 → 10.4.0-beta.1, then pre exit → 10.4.0 with a merged changelog and pre.json deleted.
  • plan.py and pre_mode.py gave the expected decision at each step, against the live GitHub Releases.
• act pull_request -j release-guards ran four scenarios: no changeset fails, with a changeset passes, Version PR head ref passes, and a PR into alpha without pre.json fails. act needed the GitHub remote set for GITHUB_REPOSITORY. Labels are now fetched with the Python standard library because the act image has no gh.
• act -n on release.yml shows the expected job plan.
• Not run locally: the version job end to end, which needs the app token and live repository writes, and the Docker build and release jobs. These are first exercised by the first Version PR after merge.
• Two independent Fable reviews, one of the plan and one of the implementation; their findings are folded in. The implementation review caught a critical bug: changesets/action leaves the Version PR's bump in the working tree, which would have made the first push with a pending changeset release the next version built from old code.
  • The fix: the step resets and cleans the tree, plan.py reads package.json from git rather than from disk, and it checks that the build commit carries the version.
  • Reproduced against a deliberately dirty tree: the plan now answers "already released".
• Head-ref exemptions apply only to same-repo branches, so a fork PR from a contributor's main is still checked.
• Plugin README.md changes are deliberately not "shipped", matching the old paths-ignore: '**.md'.

After merge (each setting confirmed first)

1. Create the alpha-protection ruleset: PR plus CI Success, no merge queue, merge commits allowed, deletion allowed, and bypass for RepositoryRole 5 and Integration 4139279.
2. Create alpha from main, run npx changeset pre enter beta, and push.
3. The frozen next branch is untouched. Archiving it is a separate decision.

🤖 Generated with Claude Code