* ci(release): require full qualification before tagging * ci(release): preserve unpublished versions and verify npm before tagging * test(release): exercise publication gates on both release routes * fix(release): fetch the live main checkpoint before verifying it * fix(release): constrain GitHub requests and workflow output * fix(release): honor GitHub label and recovery API contracts
28 KiB
Releasing REA
Pushes to main automatically open or refresh a Release Please PR with the next
version and changelog. The required CI required check runs full qualification
on the release PR's merge candidate. Review its migration notes and wait for
that check to pass. Merging the PR into main starts the release workflow.
The push caused by merging a same-repository Release Please PR skips proposal generation: the separate merged-release workflow owns tag creation and publication. This avoids looking for the new version's tag before that workflow has created it. Once the tag exists, ordinary main pushes resume proposals. API lookup failures and missing release boundaries on ordinary pushes or manual preparation still fail closed.
The Release workflow validates the merged release metadata and ancestry, then
runs full CI qualification at that exact revision. This covers coverage checks,
portable providers, and every native package host. Later main commits cannot
change or cancel that proof. The workflow rehearses the retained package,
records authorization for that candidate, then publishes to npm. The public
GitHub release and final tag are created only after the npm checks pass. MCP
Registry publication follows GitHub. Every step uses the same reviewed commit.
After qualification, a separate runner with read-only repository/actions
permissions restores the retained tarball and verifier runtime. It installs
that exact archive into an empty prefix, then exercises CLI help/discovery and
the real stdio MCP catalog/session contract. Installation finishes before the
protocol deadline begins, with dependency lifecycle scripts disabled. The npm
publisher downloads the original qualified archive and manifest, validates their
source/run/attempt,
version, Node identity and streamed digest using Node built-ins, then invokes
npm publish --ignore-scripts against the official registry. A shared built-in
registry reader checks existing bytes and tags afresh on every publisher attempt,
including retries after partial publication. It does not install
application dependencies, restore verifier code or execute package canaries.
Pinned Node/npm, Actions and the runner remain trusted toolchain inputs. Neither
job rebuilds or repacks the archive.
This rehearsal checks package consumption on the Linux release runner;
qualification retains its broader native-host and real-provider checks.
Before publishing, npm lookup failures and malformed metadata stop the job.
An existing version must match the qualified tarball's SHA-512 and intended
latest/next dist-tag before it can be reused. Publication never overwrites
an existing version or silently changes a dist-tag. After publication, confirmed
registry absence is polled every 30 seconds for a 75-minute retry window. This
covers the roughly 55 minutes between npm accepting 6.10.1 and the registry
recording it. Lookup errors and content or tag mismatches fail immediately. If
visibility takes longer, rerun the failed jobs in the original workflow once the
package appears. A separate post-publication job with read-only
repository/actions permissions verifies registry bytes and tags, then installs
from npm and repeats the same CLI/MCP checks; it also exercises a real update
from an older stable release. For a prerelease on next, that updater still
targets stable latest, as the public update command does. MCP publication
depends on that verification job succeeding. Rehearsal, publication and both
registry-verification/publication jobs do not inherit remote-cache credentials.
Qualification records the parsed latest/next channel in manifest schema v2.
Rehearsal validates its exact SemVer mapping; the minimal publisher consumes the
qualified channel without a second version parser. Only read-only recovery
accepts existing schema-v1 artifacts, preserving their original bytes and
source/run identity. New publication requires schema v2.
The required reverse-tools lane runs fresh coverage and both mutation preflights. Complete mutation sweeps run separately on a schedule or manual dispatch and do not block publication; see the testing guide. Ordinary main pushes and closed, unmerged PRs cannot publish packages. Check both publication jobs and the published-package canary; a merged PR or GitHub tag alone does not establish that publication finished. Retry failed jobs in the original run after a partial publication.
Check the packed catalog with client engines
rea-agents 6.9.0 advertised a pattern that RE2 and Rust's regex cannot
compile, so clients rejected the whole tools list
(#10830). Release qualification
runs ci.yml on the release revision, and its build job checks the advertised
catalog with every client engine and, in full qualification, Python
jsonschema; a refusal fails qualification, so publication does not start.
To check the archive itself, for example when auditing a release or
investigating a client report, install the exact qualified archive: the
package.tgz in the release run's verified-release-package artifact, which
the publish job uploads unchanged. A root npm pack is not that archive; it
lacks the release manifest, npm-shrinkwrap.json and bundled dependencies. The
check needs Go and Python 3.10 or later on the host. It runs in a subshell, so
its cleanup trap removes the archive, installed package and Python engines on
success or failure without replacing your shell's own trap.
(
set -eu
work="$(mktemp -d)"
trap 'rm -rf "$work"' EXIT
gh run download "$RELEASE_RUN_ID" --repo morluto/rea \
--name verified-release-package --dir "$work/verified"
npm install --ignore-scripts --no-save --no-package-lock --no-audit --no-fund \
--prefix "$work/prefix" "$work/verified/package.tgz"
python3 -m venv "$work/engines"
"$work/engines/bin/pip" install --require-hashes \
-r scripts/verify/advertised-schemas/requirements.txt
REA_REQUIRE_SCHEMA_ENGINES=1 REA_SCHEMA_ENGINES_PYTHON="$work/engines/bin/python" \
node scripts/verify-advertised-schemas.mjs --complete \
--package-root="$work/prefix/node_modules/rea-agents"
)
Set RELEASE_RUN_ID to the release workflow run that qualified the version.
Run it from a checkout of the release commit after npm run build:cached; the
checkout supplies the checker and the profile list, and the installed package
supplies every listing. The run must report each engine with its version,
including go regexp (RE2), re2 (C++), rust regex, rust fancy-regex,
rust jsonschema and python jsonschema; a missing engine fails instead of
passing. Report any refusal as a release defect.
Abandon an unpublished main release
If the merged candidate has a deterministic defect and npm publication has not been authorized, close that attempt before recutting its version:
gh workflow run release-abandon.yml --ref main -f release_source=MERGE_SHA
Wait for Record release abandonment to succeed. It checks that the SHA owns the current main release manifest and that the version is absent from GitHub, npm, and the MCP Registry. It also removes the abandoned PR's pending release label so Release Please can select the recut. Authorization and abandonment compete to create the same candidate-specific Git ref. Once abandonment wins, an old release run cannot obtain publication authority even if its failed jobs are rerun. Keep these refs as records.
Merge the source fix and open a reviewed rollback PR restoring only the failed
candidate's release metadata to its first parent. Review the reverse patch
before applying it, especially if the candidate or later commits also changed
product code. Restore the manifest, version pins and lockfile entries, and
remove the failed changelog section and its contribution inventory. Preserve
later unrelated work. Put Release-As: X.Y.Z in the rollback PR's squash commit
footer, using the abandoned version. Once that PR merges, Release Please uses the
previous published boundary and proposes X.Y.Z again against the corrected
source. Run the regular release PR checks on the new candidate.
If authorization won, resume the original run and qualified artifact. A successful or ambiguous npm write can become visible later, so the workflow refuses abandonment after authorization even if the registry currently reports the version absent. A published version requires a new version for changed bytes.
Recover an already published npm release
Rerunning a job uses its original workflow and source revision. When a verifier or publishing workflow needs a code fix, land that fix on main first, then use the separate recovery workflow instead of repeating release creation:
gh workflow run release-recovery.yml --ref main \
-f version=6.5.0 -f release_run_id=38564502044
Select the existing version and its original automatic Release run. Recovery requires that run's successful exact-source CI gate plus a successful npm write or registry-byte verification. It recognizes verification in either the older publisher job or the separate post-publication job. For an older release, it resolves the existing tag. If npm published before the GitHub release appeared, it resolves the source from the original qualification workflow, npm authorization and merged release PR. It uses the original qualified tarball and verifier runtime. Expired or missing artifacts stop recovery. The archive's source, version, original run/attempt and Node version must match, and its SHA-512 must equal npm's published integrity. The corrected controller runs the public CLI, MCP catalog/session and previous-version update canary against that released runtime. The installation completes before MCP's handshake begins; dependency lifecycle scripts are disabled as in the installed-package verifier.
After verification succeeds, recovery completes the GitHub release and tag if
needed, then publishes the verified server.json to MCP Registry. It performs
no npm writes. Both publication paths share the same
MCP publisher: a paginated registry lookup preserves an identical active
version, refuses conflicting/inactive metadata, and fails on lookup errors.
The original failed run remains a historical failure; the recovery run records
the new verification and remaining registry publication. Manual frozen-branch
releases are outside this recovery path.
For a release that needs an independently frozen application checkpoint, use the optional manual path below. It retains explicit prepare and publish phases.
Automatic main proposals and manual checkpoint preparation use
scripts/release-proposal.mjs with the pinned release-please dependency.
The controller applies patches/release-please+17.3.0.patch only when invoked;
normal dependency installation and published-package installation do not apply it.
The patch avoids commit-file backfills, associated PR file lists and path splitting
for a single root Node package with the default changelog, default or
always-bump-minor versioning, no path exclusions and no explicit plugins. Other
configurations retain the upstream file attribution workflow. Commit history and
associated PR metadata still come from GitHub: release notes need the commits,
and BEGIN_COMMIT_OVERRIDE needs the merged PR body. Skipped file lists remain
unknown rather than being reported as empty. The controller sizes commit search
from the complete selected Git history, and a missing known release boundary
fails before proposal creation.
History-page reads retry GitHub's canonical internal GraphQL response error within the existing five-retry budget and exponential backoff. Each retry uses the same cursor; permission, validation and mixed errors fail immediately. Exhaustion stops preparation before proposal writes. The controller does not restart proposal creation or retry mutations. An internal GraphQL error does not establish API quota exhaustion or prove that query size caused the failure. Publication continues through the pinned release-please action.
A nonzero manifest version must resolve to a GitHub release or tag before
proposal history is collected. If publication has not created that boundary
yet, preparation stops before opening or updating a PR; wait for publication
before retrying. Missing manifest versions and 0.0.0 still allow an initial
release. This prevents historical Release-As directives from being replayed
as unreleased changes.
When upgrading release-please, review the upstream manifest implementation, refresh the versioned patch and run the release proposal and workflow boundary tests. Version mismatch or a patch that neither applies cleanly nor matches an already-applied patch fails closed.
Contributor-aware release notes
Use the rea-changelog-update skill
to turn the bot draft into grouped Highlights, Changes, and Fixes with inline
Thanks @... credit. npm run release:notes -- inventory collects the full
selected Git range and paginated GitHub PR/author/closing-issue metadata;
record --summary produces a compact provenance link for public notes, while
record produces the full record for review. Credit a contribution once even
when it appears in highlights, details and migrations; omit maintainer
@morluto self-thanks. Keep complete authorship metadata in the inventory
instead of duplicating a credit ledger in the release body. check validates credits
and optional PR-body equality, and render writes the verified release section.
Run a subcommand without its required options to see its usage. GitHub reads
require an authenticated gh; record/check/render work offline from the saved
inventory and complete local Git history.
Save a finalized inventory on the release branch at
docs/releases/VERSION.contributions.json. Review unknown identities and
reverted/backported work explicitly; GitHub metadata does not establish the
quality of a user-facing claim. Preserve the existing breaking-change section
and checkpoint checks. The contribution inventory is a reviewed snapshot, not
a signed attestation; the offline checker verifies local range coverage and
credit consistency, not GitHub's authorship independently.
Before editing the live PR, add rea:release-notes-finalized to prevent ordinary
main-push proposals from overwriting the editorial notes. Wait for any already
running proposal to finish. The guard applies to main-push automation; do not
run manual checkpoint preparation over finalized notes. Remove the label to
resume bot regeneration. The label does not freeze the base branch: new base
commits require re-inventorying and re-reviewing the notes.
Update both the release branch's CHANGELOG.md and the PR body, preserving
Release Please's surrounding metadata. Keep Author readiness declarations and
other PR metadata outside the first and last standalone --- notes delimiters.
The version heading must start the notes within those delimiters (or use Release
Please's generated component wrapper). The checker uses Release Please's parser
to verify that publication will extract the reviewed notes.
Before creating a release, the workflow checks an inventory when present, requires its target to equal the reviewed merge's first parent, and compares the freshly fetched PR body to the changelog. It rejects changes outside the release metadata paths and stale credit records before any tag or publication. Review the diffs within allowed metadata paths as well, especially package dependencies and scripts. Existing candidates without inventories retain their current checks. Merging still starts publication; a notes edit does not authorize a merge or release by itself.
The checker supports inline Release Please PR bodies up to GitHub's 65,536 character limit, including the surrounding header/footer. Overflow-link PR bodies need a separate integration and fail explicitly; credits are never silently truncated.
1. Select a source for a manual checkpoint
Use the next minor version proposed by Release Please, including releases with
breaking changes. Record the full source SHA and create release/VERSION at
that commit. The selected version and Release Please's proposed version must
agree before publication.
When choosing the manual path, leave the automatic main release PR unmerged. Select the application commit from main, create the frozen branch, and prepare its own release PR using the steps below. Merging the main release PR starts automatic publication instead. Close the superseded main PR after the manual release has published, before merging the metadata synchronization PR back to main.
release/VERSION also sets the expected version for the workflow. Use an exact
SemVer such as release/6.1.0 or release/6.1.0-rc.1, without build metadata.
The checkpoint validator rejects a candidate whose package, lockfile, manifest,
registry metadata or changelog disagrees with that version before creating a tag.
Compatibility and version selection
Before publishing a candidate, review its changelog's breaking changes and the migration notes for the release being prepared. The 6.1 to 6.2 migration guide records that release's changes; it is a historical reference, not the compatibility checklist for later releases.
REA uses Release Please's always-bump-minor strategy: every release increments
minor and resets patch, including releases with breaking changes. For example,
the next release after 6.0.0 is 6.1.0. Version numbers use the SemVer format,
but a minor increment does not promise backward compatibility. Review the
changelog's breaking-change section and migration notes before upgrading.
The supported public surface includes documented CLI commands/options, MCP tool
names and input/result contracts, saved evidence formats and supported runtime
requirements. Before adding ! or a BREAKING CHANGE footer, a PR must identify
a previously valid call or configuration that will fail or change meaning,
explain why compatibility cannot be preserved, and give its migration. Prefer
optional additions, compatibility adapters and a documented deprecation period.
Keep breaking markers so the bot includes migration notes without incrementing
major. Maintainers review this impact before merging; the bot parses markers
and cannot infer compatibility.
For example, adding an optional inspection tool is a minor change. Rejecting a relative MCP path previously accepted by the public contract is breaking; rejecting an input that the existing contract already prohibited is a fix. Changing the version number alone does not restore compatibility.
For example, after selecting a reviewed commit for 5.0.0:
git fetch origin main
git branch release/5.0.0 SOURCE_SHA
git push origin release/5.0.0
Replace SOURCE_SHA with the selected full commit SHA. The checkpoint must
include this release workflow and CI support for release branches. For an
older checkpoint, backport only the release infrastructure first and record
that additional commit. Do not merge later implementation changes into the
release branch or rebase the candidate onto a moving main.
2. Prepare the bot PR
Run the workflow definition from main and select the frozen source separately:
gh workflow run release.yml --ref main \
-f release_branch=release/5.0.0 -f phase=prepare
Release Please targets that branch and prepares its version, changelog, and
registry metadata. The workflow uses an optional RELEASE_PLEASE_TOKEN
repository secret and otherwise uses the built-in GITHUB_TOKEN. A dedicated
GitHub App or personal access token can start PR CI automatically. With the
built-in token, opened, synchronize, and reopened PR events create runs
that require a maintainer with write access to approve them. See
GitHub's workflow trigger documentation.
The generation step normalizes the product catalog. Preparation cannot create a GitHub release or publish a package. Record the final bot PR head after normalization, then approve that head's blocked runs from the PR page. Updates to the bot branch can create new approval-required runs; approval of an older head does not verify the normalized candidate. Wait for the final head's CI.
The validator reads the actual ancestry range from the published baseline tag
to the selected checkpoint, including visible first-parent Conventional Commits
and the PR titles in GitHub's default merge messages. The report preserves the
original merge subject alongside the extracted Conventional Commit title.
This matters after merging a side-branch release back into a newer main:
Release Please's chronological history cutoff can omit unreleased mainline
commits. Under always-bump-minor, unreleased breaking markers allow a minor
increment and still require references in the new release's breaking-change
migration section. Checkpoints using the default strategy retain the major
increment requirement. Other omitted entries are reported for review.
Historical notes from an older release cannot satisfy
the new release's migration check. This audits declared markers and references;
it does not prove API compatibility or the quality of a migration explanation.
If preparation reports a mismatch or omitted breaking changes, inspect the recorded ancestry report, correct the release PR's version artifacts and notes, regenerate documentation, and review/test its final head. Do not repeatedly prepare over manual corrections. Publication independently checks the merged candidate again before Release Please can create a tag.
Review the candidate's version, notes, generated metadata, and package contents. Wait for the candidate's CI and relevant real-provider checks. Routine local iterations need focused checks; CI owns full deterministic coverage and platform lanes. If an artifact or real-provider check is unavailable, report that limit before deciding to publish.
Merge the reviewed PR into release/5.0.0 with its head SHA matched. Further
main commits do not change this candidate. A necessary release fix belongs
on the release branch, must be reviewed and tested, and establishes a new
recorded checkpoint.
3. Publish the reviewed merge
After the release PR has merged:
gh workflow run release.yml --ref release/5.0.0 \
-f release_branch=release/5.0.0 -f phase=publish
Publication uses the exact merged bot PR revision without preparing or updating
another PR. npm verification completes before Release Please creates the public
release and tag. The MCP Registry job uses the same verified commit.
Stable versions publish to npm's latest tag; prerelease versions publish to
the next tag so they cannot replace the stable install by default.
The publish dispatch runs from the frozen release branch so npm's provenance
records the actual release commit. Before npm publication, the workflow validates
the dispatch, qualifies and rehearses the selected revision, and rechecks that
the branch tip still equals the dispatch SHA. Registry jobs run only during
publish. A GitHub tag pointing to a different commit stops MCP publication.
See npm's provenance implementation
for the use of GitHub's workflow ref and commit SHA.
Full qualification builds the bundled Windows controls and verifies the packaged artifact on its native hosts. The Linux x64 verifier retains the exact tarball it installed and tested, after its workspace cleanup completes. The npm job downloads that archive from the same workflow run and checks its source SHA, run identity/attempt, package and Node versions, host identity, and SHA-256. It publishes that archive without rebuilding or repacking it. Re-running failed publisher jobs can reuse a prior successful attempt from the same run. The workflow then verifies the published CLI, the capability-scoped MCP catalog, and the isolated package update path before publishing MCP Registry metadata.
Record these outcomes separately:
- GitHub release and tag, including the resolved commit SHA.
- npm's exact version and integrity, with the published-package canary passed.
- MCP Registry's exact server version and matching npm package version.
A GitHub tag alone does not establish npm or MCP Registry publication.
4. Sync metadata back to main
Manual checkpoint synchronization is part of completing that release. Finish it before cutting the next checkpoint; otherwise main retains the previous release baseline and can propose an already-published version again.
After publication, open a PR from the release branch back to main. Preserve main's later implementation changes and regenerate ignored build outputs from the combined contracts with the released package version. Before merging, check whether GitHub permits merge commits:
gh api repos/morluto/rea --jq .allow_merge_commit
If disabled, a maintainer must arrange an approved ancestry-preserving merge path before synchronization can finish. Squash and rebase merges do not put the released tag in main's ancestry. Do not substitute them for this step. Review and test this synchronization PR, then use a merge commit so the release tag remains in main's ancestry. Keep the released tag unchanged.
The synchronization must include .release-please-manifest.json,
package.json, both root versions in package-lock.json, CHANGELOG.md,
server.json, the Claude Code and Codex plugin manifests
(.claude-plugin/plugin.json and .codex-plugin/plugin.json), the Codex
server declaration (.codex-plugin/mcp.json), the Cursor Marketplace manifest
(.cursor-plugin/plugin.json) and server pin (mcp.json), both
marketplaces (.claude-plugin/marketplace.json and
.agents/plugins/marketplace.json), and the versioned documentation examples. Run
npm run docs:generate, npm run docs:check, and the release configuration
tests against the combined tree. After the merge, verify that the released
tag is an ancestor of main:
git fetch origin main --tags
git merge-base --is-ancestor rea-agents-5.0.0 origin/main
Close the superseded main proposal before merging the synchronization PR. That merge's main push opens a proposal for the following release using the updated baseline. Future releases can use the automatic main PR or repeat the manual checkpoint procedure; automatic proposals do not move frozen branches. Preparation generates and validates the catalog, portable conformance projections, and packaged skill from the candidate checkout without committing them. The checkpoint validator binds tracked version authority to the source SHA; generated-catalog and package checks validate the derived representation. No generated-metadata workflow pushes follow-up commits onto feature or release branches.
Partial publication and retries
Inspect the failed job and public registry state before retrying. When npm is already published, the npm job verifies that exact version instead of publishing it again. Re-run failed jobs in the original publication run so its release SHA and outputs stay fixed. If only MCP publication failed, retry that job after checking that the npm canary succeeded.
A branch tip that moved after dispatch fails before Release Please creates a tag. Do not dispatch a fresh publish phase to repair an already-created release: Release Please will not create the same release again. Do not move the tag, delete the release, or unpublish npm as a retry. A defective public package requires a reviewed correction and a new version.
Plugin artifact metadata
Package verification selects files with npm, then packs an owned staging directory.
The release manifest omits development dependencies and development-only overrides;
its generated npm-shrinkwrap.json preserves the runtime dependency resolutions
and integrity values from package-lock.json. Runtime or unresolved overrides
fail packaging rather than being dropped. Source metadata is never rewritten.
The archive bundles production dependencies because Codex fetches npm plugins
without installing dependencies. The producer includes all locked PTY platform
archives after checking their integrity, without re-resolving the runtime tree.
Optional Frida stays outside the bundle so ordinary npm installation can retain
its host-specific installer. This also lets Claude install locked dependencies under its plugin policy while
retaining development security overrides. Both plugin marketplaces select the
same qualified npm artifact, which the release workflow publishes unchanged.