Release operations
Ticket #275. A version tag is the only path that publishes Ensemble. This page records the release workflow, the main-branch protection, the credential boundary, and the dry-run rehearsal. Use the release sign-off checklist before creating the tag.
Current release
@heyimteee/ensemble@0.1.1 is the stable release, published from tag v0.1.1 and marked as a normal GitHub release, not a prerelease. npm dist-tags are latest: 0.1.1 and next: 0.1.0-rc.3. This is a documentation and npm presentation patch; the runtime is identical to 0.1.0 (and to 0.1.0-rc.3). Pin the exact version for deliberate installs.
The historical 0.1.0-rc.2 release remains at tag v0.1.0-rc.2 (release commit ccd13eb) as the first public prerelease. The release-candidate verification tag rc-0.1.0-rc.2 at d74fc3d predates the #281–#284 fixes; it is an evidence base, not a publish source, and must not be moved. #285 changes the CI workflows and contract checker; #286 adds OpenCode 2.3.0 support; #287 hardens live TUI readiness with no product runtime change. Required CI at a7f1eb3 is green on the first attempt: Verify, Compatibility (OpenCode 2.2.6, 2.2.7, and 2.3.0), Docs, and Node Matrix. Both 4-hour soaks, the full macOS checklist including 1.7, and the public-registry install smoke on 2.2.7/2.3.0 pass. See the parent #268 record and the soak record. If any runtime source changes, rerun the clean-install proof before a future tag.
The stable release notes are Ensemble 0.1.1; the historical prerelease notes and launch plan remain rc.2 and rc.2 launch plan. The release sign-off and parent #268 verification are the prerelease evidence.
Required checks and main protection
main is protected by the repository ruleset main protection (ruleset id 27380159), applied on 2026-11-16 with gh api. The ruleset targets the default branch and is active:
| Rule | Setting |
|---|---|
| Deletion | Blocked |
| Non-fast-forward | Blocked |
| Pull request | 1 required approval, stale reviews dismissed on push, last-push approval required, unresolved review threads block merge |
| Required status checks | Strict: the branch must be up to date and every check below must pass |
| Bypass | Repository admin role only |
The required contexts are the real GitHub Actions check names, not the workflow file or job id. They come from REQUIRED_STATUS_CHECKS in src/v2/ci-workflows.ts; the contract test proves each one is produced by a checked-in workflow.
verify
live-fake
live-native
live-multilocation
latency-smoke
docs:check
verify (Node 22.23.4)
verify (Node 24.22.1)
verify (Node 26.12.1)
OpenCode 2.2.6
OpenCode 2.2.7
OpenCode 2.3.0Inspect the applied state without changing it:
gh api repos/heyimteee/ensemble/rulesets
gh api repos/heyimteee/ensemble/rulesets/27380159The authenticated maintainer holds the repository admin role and is therefore the only bypass actor. Bypassing the review requirement is an emergency action: it is logged by GitHub, and the reason belongs in the release sign-off. Do not rename a workflow job or change the Node/OpenCode matrix without updating REQUIRED_STATUS_CHECKS and this list; a required context that no workflow produces blocks every pull request indefinitely.
The docs-rationale workflow is in the repository but is not one of the contexts above and is not yet required on main. Making it required needs an explicit maintainer decision and a GitHub ruleset change, which this repository does not apply automatically. Until then it reports on the pull request as an advisory check; a program merge can proceed without claiming external enforcement.
Release workflow
.github/workflows/release.yml has two triggers:
pushof a tag matchingv*— a real release;workflow_dispatch— always a dry run. The publish jobs are gated to a tag push, so a manual dispatch cannot publish.
A plain branch push or a pull request cannot reach the publish jobs.
| Job | What it does | Runs when |
|---|---|---|
release-preflight | Validates the tag against package.json, extracts the changelog section into RELEASE_NOTES.md, exports version, tag, dry-run, and dist-tag | Always |
package | npm ci, npm run verify, npm run docs:check, npm run build, npm pack, CycloneDX SBOM, artifact upload | Always |
publish-dry-run | npm publish --dry-run --access public --tag "$DIST_TAG" with no registry secret | Dry run only |
publish | npm publish --provenance --access public --tag "$DIST_TAG" with id-token: write (npm trusted publishing; no long-lived token) | Tag push only |
github-release | Creates the GitHub release from the changelog notes and attaches the SBOM, tarball, notes, and changelog | Tag push only |
The default workflow permission is contents: read. Only the publish job adds id-token: write; only the GitHub release job adds contents: write. The workflow does not print a secret, enable shell tracing, or contain a private absolute path.
Credential setup
- npm publishing uses trusted publishing (OIDC): the workflow grants
id-token: writeonly to the publish job, and npm accepts the signed GitHub identity. There is noNPM_TOKENrepository secret to create, rotate, or leak. - Provenance needs
id-token: writeand a public package. The workflow runsnpm publish --provenance --access public; npm signs the artifact through GitHub's OIDC provider. - npm refuses a prerelease without an explicit dist-tag. The preflight exports
nextfor a version with a prerelease suffix andlatestfor a final release, and both publish jobs pass--tag "$DIST_TAG". npm also requires alatesttag and rejects deleting it (E400). Stable0.1.1ownslatest;0.1.0-rc.3remains onnext. Pin exact versions. - Never put a registry credential, token, tag message, or private path in a workflow file or issue.
Dry run
Start it from Actions → Release → Run workflow. The run needs no npm credential and publishes nothing:
gh workflow run release.ymlA local rehearsal runs the same gates without a registry token:
npm run verify
npm run docs:check
node --experimental-strip-types scripts/release-guard.mjs \
--event workflow_dispatch --ref refs/heads/main \
--manifest package.json --changelog CHANGELOG.md --out RELEASE_NOTES.md
npm run build
npm pack --json
npm sbom --sbom-format=cyclonedx --package-lock-only > "ensemble-$(node -p "require('./package.json').version").cdx.json"
npm publish --dry-run --access public --tag next # latest for a final versionnpm publish --dry-run runs the same prepack build and content guard as a real publish, so a tarball with raw TypeScript, tests, fixtures, docs, or a missing export fails before any upload.
Tagged release
- Approve the release and its notes, launch plan, and sign-off (#278). The current published release is stable
0.1.1; a later release bumps the patch version and records its own notes. Do not move thev0.1.1tag. - Confirm
versioninpackage.jsonandpackage-lock.jsonagree; open the release pull request and let every required check pass. - Merge to
main, then tag the merge commit:shversion=$(node -p "require('./package.json').version") git tag -a "v$version" -m "Ensemble release" git push origin "v$version" - Watch the
Releaseworkflow. The preflight refuses a tag that disagrees withpackage.jsonor a version with no changelog section. - Confirm the npm provenance attestation, the GitHub release, and the attached CycloneDX SBOM before announcing.
The GitHub release body is the changelog section, and the notes file, tarball, SBOM, and CHANGELOG.md are attached as release assets. The notes are never generated from commit messages, so an unnoticed change cannot silently become the announcement.
Failure and rollback
- A failed preflight, verify, docs, pack, or dry run publishes nothing.
- A failed real publish leaves the tag in place; fix forward with a new patch version. Do not move a published tag.
- A bad published release follows package rollback: reinstall the previous exact version, restore state only when the older release cannot read newer rows, and prefer
npm deprecateplus a patch release overnpm unpublish. npm only permits unpublishing within 72 hours and only when no other package depends on the version. - A bad GitHub release can be edited or deleted; the npm artifact and the tag are the durable record.
Sign-off
Complete the release sign-off checklist. The checklist covers security, the MIT license and legal review, package contents, rollback, support readiness, and the clean-install proof. A blocked check is not a pass; record it as blocked and decide explicitly whether to release.