Skip to content

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:

SettingApplied value
Ruleset id27380159
TargetDefault branch (~DEFAULT_BRANCH)
Enforcementactive
DeletionBlocked
Non-fast-forwardBlocked
Required approvals1
Stale reviewsDismissed on push
Last-push approvalRequired
Review threadsMust be resolved
Required checksStrict (branch must be up to date)
BypassRepository 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:

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

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

TriggerModeResult
push tag v*Real releasePreflight, package, provenance publish, GitHub release
workflow_dispatchDry run (always)Preflight, package, npm publish --dry-run; no secret, no publish
Branch push or pull requestNot triggeredNo job can reach the publish step
  • release-preflight validates the tag against package.json, extracts the changelog section into RELEASE_NOTES.md, and exports version, tag, dry-run, and dist-tag.
  • package runs npm ci, npm run verify, npm run docs:check, npm run build, npm pack, and npm sbom --sbom-format=cyclonedx --package-lock-only, then uploads the tarball, SBOM, and pack report.
  • publish-dry-run uses npm publish --dry-run --access public --tag "$DIST_TAG" and has no secrets. reference.
  • publish is gated to a tag push, grants id-token: write, reads NODE_AUTH_TOKEN from secrets.NPM_TOKEN, and runs npm publish --provenance --access public --tag "$DIST_TAG".
  • github-release is gated to a tag push, grants contents: write, and creates the release from RELEASE_NOTES.md with the SBOM, tarball, notes, and CHANGELOG.md attached.
  • A prerelease publishes under next; a final release publishes under latest. 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 ​

CheckResultEvidence
npm run verifyPASSStrict typecheck; 2,098 tests, 0 failed/skipped
npm run docs:checkPASSContract v7; OpenCode 2.2.6/2.2.7; Node >=22.23.4
Release workflow contractPASS30 release/CI tests; YAML parses with the five expected jobs and two trigger forms
npm pack --dry-runPASS@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-onlyPASSCycloneDX 1.5; 383 locked components
npm publish --dry-run --access public --tag nextPASS+ @heyimteee/ensemble@0.1.0-rc.2; no credential and no upload
Release preflight, dry-run pathPASSmanual dispatch -> 0.1.0-rc.2 (dry run, next); notes extracted
Release preflight, tag mismatchPASStag v0.1.0 does not match package version 0.1.0-rc.2; exit 1
Branch protectionPASSRuleset 27380159 active with the 11 real check contexts and 1 approval
Public npm publishNOT RUNBy design; requires NPM_TOKEN and a v* tag
GitHub-hosted dry runBLOCKEDworkflow_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 creationNOT RUNDepends on the tag publish; deferred to #278
macOS/Herdr installBLOCKEDDeferred 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-fake suite. 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_TOKEN must 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.

Released under the MIT License.