Release workflow, branch protection, and publish provenance
Status: PASS (dry run; no public publish) Date: 2026-11-16 Ticket: #275 Parent spec: #268 Branch: ticket/275-release
Scope
This record covers the repo-side release contract: the protected default branch, the tag-driven workflow with a token-free dry run, npm provenance and the CycloneDX SBOM, the changelog-based GitHub release, and the release sign-off checklist. It does not publish to the public npm registry, use a real npm credential, or create a tag. The final 0.1.0 notes and launch sign-off belong to #278; macOS/Herdr belongs to #277.
Branch protection
main was unprotected at the start (GET branches/main/protection returned Branch not protected) and the authenticated account reported {"admin": true} on repos/heyimteee/ensemble. The repository ruleset main protection was applied with gh api:
| Setting | Applied value |
|---|---|
| Ruleset id | 27380159 |
| Target | Default branch (~DEFAULT_BRANCH) |
| Enforcement | active |
| Deletion | Blocked |
| Non-fast-forward | Blocked |
| Required approvals | 1 |
| Stale reviews | Dismissed on push |
| Last-push approval | Required |
| Review threads | Must be resolved |
| Required checks | Strict (branch must be up to date) |
| Bypass | Repository admin role (actor_id 5), documented |
The required contexts are the check names reported by the existing workflows, read back from the repository, not the workflow file or job id:
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.7GET rulesets/27380159 returns those 11 contexts, the pull-request rule, and bypass_actors: [{"actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always"}]. GET rules/branches/main lists the deletion, non-fast-forward, pull-request, and required-status-checks rules. The maintainer holds the only bypass; using it is an explicit, logged action for a solo-maintainer review exception and is recorded in the sign-off.
REQUIRED_STATUS_CHECKS in src/v2/ci-workflows.ts is the canonical list. A contract test derives the job names and matrix values from verify.yml, docs.yml, node-matrix.yml, and compatibility.yml, and fails if the constant, the workflows, or docs/operations/release.md disagree.
Release workflow
.github/workflows/release.yml is the only publishing path:
| Trigger | Mode | Result |
|---|---|---|
push tag v* | Real release | Preflight, package, provenance publish, GitHub release |
workflow_dispatch | Dry run (always) | Preflight, package, npm publish --dry-run; no secret, no publish |
| Branch push or pull request | Not triggered | No job can reach the publish step |
release-preflightvalidates the tag againstpackage.json, extracts the changelog section intoRELEASE_NOTES.md, and exportsversion,tag,dry-run, anddist-tag.packagerunsnpm ci,npm run verify,npm run docs:check,npm run build,npm pack, andnpm sbom --sbom-format=cyclonedx --package-lock-only, then uploads the tarball, SBOM, and pack report.publish-dry-runusesnpm publish --dry-run --access public --tag "$DIST_TAG"and has nosecrets.reference.publishis gated to a tag push, grantsid-token: write, readsNODE_AUTH_TOKENfromsecrets.NPM_TOKEN, and runsnpm publish --provenance --access public --tag "$DIST_TAG".github-releaseis gated to a tag push, grantscontents: write, and creates the release fromRELEASE_NOTES.mdwith the SBOM, tarball, notes, andCHANGELOG.mdattached.- A prerelease publishes under
next; a final release publishes underlatest. npm refuses a prerelease without an explicit tag, which the first dry run exposed; the preflight now supplies it.
CHANGELOG.md is the release-notes source. A version without a non-empty section fails the preflight, so notes cannot be generated from commit messages. docs/operations/release.md records the process, credential boundary, and protection; docs/operations/release-signoff.md covers security, MIT license/legal, package contents, rollback, support readiness, and the clean-install proof.
Results
| Check | Result | Evidence |
|---|---|---|
npm run verify | PASS | Strict typecheck; 2,098 tests, 0 failed/skipped |
npm run docs:check | PASS | Contract v7; OpenCode 2.2.6/2.2.7; Node >=22.23.4 |
| Release workflow contract | PASS | 30 release/CI tests; YAML parses with the five expected jobs and two trigger forms |
npm pack --dry-run | PASS | @heyimteee/ensemble@0.1.0-rc.2; 124 files; 503,985 bytes; 121 built JS files; runtime-only contents |
npm sbom --sbom-format=cyclonedx --package-lock-only | PASS | CycloneDX 1.5; 383 locked components |
npm publish --dry-run --access public --tag next | PASS | + @heyimteee/ensemble@0.1.0-rc.2; no credential and no upload |
| Release preflight, dry-run path | PASS | manual dispatch -> 0.1.0-rc.2 (dry run, next); notes extracted |
| Release preflight, tag mismatch | PASS | tag v0.1.0 does not match package version 0.1.0-rc.2; exit 1 |
| Branch protection | PASS | Ruleset 27380159 active with the 11 real check contexts and 1 approval |
| Public npm publish | NOT RUN | By design; requires NPM_TOKEN and a v* tag |
| GitHub-hosted dry run | BLOCKED | workflow_dispatch registers from the default branch; this branch is not merged. Every workflow gate was rehearsed locally and the structure is contract-tested |
| GitHub release creation | NOT RUN | Depends on the tag publish; deferred to #278 |
| macOS/Herdr install | BLOCKED | Deferred to #277 |
The local dry run used no npm token and no public registry write. The npm warning that the command requires login is expected for --dry-run; the command exited 0 and printed no upload.
Residual risks
- The required checks include the long
live-fakesuite. A red suite blocks a merge until it is fixed or the documented admin bypass is used. - The repository is maintained by one account, so the one-approval rule cannot be satisfied without the explicit admin bypass. Bypass use belongs in the sign-off.
NPM_TOKENmust exist before the first tag. Without it the publish job fails safely before any upload.- The SBOM is built from the lockfile and therefore includes locked development dependencies as well as runtime dependencies. That is conservative for an artifact SBOM; it is not a claim that dev packages ship.
- A failed publish leaves the tag; fix forward with a new patch version rather than moving a published tag.
- The first GitHub-hosted run is the first real execution of the workflow. The dry-run dispatch should be run immediately after this branch reaches the default branch and before the release tag.