Files
hyperframes/docs/contributing/release-channels.mdx
T
Miguel Ángel c106793f79 fix(release): publish to npm with the job's OIDC token, not a stored token (#8070)
* test(release): npm publishes with the job's OIDC token, no stored token named

* fix(release): publish to npm with the job's OIDC token, not a stored token

* test(release): catch a secret named by index or inherited, not only secrets.X
2026-11-17 12:20:49 +00:00

80 lines
5.4 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Release channels
description: How HyperFrames keeps alpha-only work out of stable releases.
---
HyperFrames publishes two release channels:
- Stable releases use versions like `0.4.24` and publish to the npm `latest` dist-tag.
- Prereleases use versions like `0.4.24-alpha.1` and publish to the npm dist-tag named by the prerelease suffix, such as `alpha`. The suffix must be one of `alpha`, `beta`, `rc`, `next`, `canary`, `hdr`, `native` or `desktop`, in lower case. The publish workflow refuses any other suffix before it publishes.
## Branch policy
Use branch separation to decide what code is eligible for each release channel.
Dist-tags only control npm install defaults; they do not remove code from a package.
- `main` is stable/releasable. Anything merged to `main` is eligible for `latest`.
- `release/v*` branches are for stable patch releases and hotfixes.
- `next` and `alpha` are the prerelease branches. A prerelease tag publishes only a commit already on `main`, `next` or `alpha`.
If a feature should ship in alpha only, merge or retarget that PR to a prerelease branch instead of `main`.
## Stable release
Stable releases publish only when a reviewed `release/vX.Y.Z` PR merges into protected `main`.
Prepare and review release notes before creating the release commit:
```bash
bun run release:prepare <version>
```
On the first run, `release:prepare` drafts missing changelog artifacts and exits non-zero for review so chained release commands stop before tagging. After the generated TODO summary is rewritten, rerun the same command to create the release commit and tag.
See [Changelog process](/contributing/changelog-process) for the full workflow. For stable releases, `bun run set-version <version>` still enforces this checkpoint when maintainers run the lower-level release command directly.
Push the release branch without its local tag, open a PR to `main`, and merge it after approval and CI. The publish workflow checks out the exact PR merge SHA, verifies it before publishing, creates the stable tag at that commit, publishes npm packages, and creates the GitHub release. Nothing waits for an approval after the merge: the reviewed release PR is the review.
If that workflow needs recovery, rerun its original merged-PR event. Stable tag pushes and manual dispatches do not publish, so recovery cannot select a different commit.
For hotfixes, branch from the last stable tag, cherry-pick only the fix, publish the patch release, then merge or cherry-pick the same fix back into the prerelease branch.
## Alpha release
Alpha releases must be reachable from `origin/main`, `origin/next` or `origin/alpha`. The publish workflow refuses a tag on any other commit before it builds anything.
Use the same changelog draft workflow when the prerelease contains changes that users should know about.
```bash
git checkout next
bun run set-version 0.4.25-alpha.1
git push origin next
git push origin v0.4.25-alpha.1
```
The tag push starts the publish workflow, which builds, packs and publishes the release with no approval step. Only repository admins may push `v*-*` tags.
Consumers can install alpha builds explicitly:
```bash
npm install hyperframes@alpha
npm install @hyperframes/core@alpha
```
## CI guardrails
The publish workflow validates release channel boundaries before publishing:
- Stable versions must publish with `latest`.
- Prerelease versions must publish with the prerelease dist-tag, such as `alpha`.
- Stable releases must come from a merged `release/vX.Y.Z` PR whose final commit a maintainer with write access approved. That maintainer must not have opened the PR, or written, committed or force-pushed its commits. Reviews from accounts without write access count neither as approvals nor as change requests.
- Prerelease tags must point at a commit already on `main`, `next` or `alpha`.
- Only repository admins may push prerelease (`v*-*`) tags. That is a prerelease's only review: a prerelease branch takes pushes without a PR, and no approval follows the tag.
- Every publish runs in the `npm-publish` environment, which npm trusted publishing names; it waits for no approval.
- Merged `release/vX.Y.Z` PRs publish stable releases only.
- Every publish job verifies that its checkout matches the immutable event SHA.
- Builds, lifecycle scripts and `npm pack` run in a job with a read-only token and no secrets.
- The job that publishes to npm runs no code from the release commit, and it holds no stored npm token: npm trusted publishing authenticates it with the job's OIDC token. It checks that every packed tarball is a package this workflow publishes, at exactly the release version, then uploads it with lifecycle scripts off.
- A version already on npm is skipped only when its contents match the original run’s tarball, including on a retry. Different contents fail the publish.
- The Lambda handler zip and arm64 video image are built by the run, and `@hyperframes/aws-lambda` pins those builds. Retries reuse the original immutable run bundle. If the version is already on npm, its verified package must pin those same bytes before any release mutation. A separate immutable run receipt binds the release ID and asset digests; foreign releases and mismatched assets fail instead of being adopted or overwritten. See [publish recovery](/contributing/changelog-process) for retention and recovery limits.
This prevents an alpha-only feature from being included in a stable hotfix by accident.