Skip to content

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:

RuleSetting
DeletionBlocked
Non-fast-forwardBlocked
Pull request1 required approval, stale reviews dismissed on push, last-push approval required, unresolved review threads block merge
Required status checksStrict: the branch must be up to date and every check below must pass
BypassRepository 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.

text
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.0

Inspect the applied state without changing it:

sh
gh api repos/heyimteee/ensemble/rulesets
gh api repos/heyimteee/ensemble/rulesets/27380159

The 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:

  • push of a tag matching v* — 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.

JobWhat it doesRuns when
release-preflightValidates the tag against package.json, extracts the changelog section into RELEASE_NOTES.md, exports version, tag, dry-run, and dist-tagAlways
packagenpm ci, npm run verify, npm run docs:check, npm run build, npm pack, CycloneDX SBOM, artifact uploadAlways
publish-dry-runnpm publish --dry-run --access public --tag "$DIST_TAG" with no registry secretDry run only
publishnpm publish --provenance --access public --tag "$DIST_TAG" with id-token: write (npm trusted publishing; no long-lived token)Tag push only
github-releaseCreates the GitHub release from the changelog notes and attaches the SBOM, tarball, notes, and changelogTag 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: write only to the publish job, and npm accepts the signed GitHub identity. There is no NPM_TOKEN repository secret to create, rotate, or leak.
  • Provenance needs id-token: write and a public package. The workflow runs npm 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 next for a version with a prerelease suffix and latest for a final release, and both publish jobs pass --tag "$DIST_TAG". npm also requires a latest tag and rejects deleting it (E400). Stable 0.1.1 owns latest; 0.1.0-rc.3 remains on next. 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:

sh
gh workflow run release.yml

A local rehearsal runs the same gates without a registry token:

sh
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 version

npm 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 ​

  1. 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 the v0.1.1 tag.
  2. Confirm version in package.json and package-lock.json agree; open the release pull request and let every required check pass.
  3. Merge to main, then tag the merge commit:
    sh
    version=$(node -p "require('./package.json').version")
    git tag -a "v$version" -m "Ensemble release"
    git push origin "v$version"
  4. Watch the Release workflow. The preflight refuses a tag that disagrees with package.json or a version with no changelog section.
  5. 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 deprecate plus a patch release over npm 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.

Released under the MIT License.