Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
9.9 KB
Raw Blame

Releasing to npm with trusted publishing

The public Release Process is the operational authority. This page explains the repository and npm mechanics.

Astryx publishes its public @astryxdesign/* packages from GitHub Actions through npm trusted publishing (OIDC). CI carries no long-lived npm publish token. Every stable package is built from an immutable release tag and published with provenance.

Release sequence

  1. Run the canonical full-scope release-check on an exact commit from current main. That commit also needs a passing full unit run of the Main workflow: main's scheduler dispatches one with every release-check of main's tip, a person's included, within about 15 minutes while that commit is still the tip. A release owner can also dispatch the Main workflow beside their own check with sha set to the checked commit, which tests exactly that commit; a dispatch without sha tests whatever is main's tip when it starts and is no receipt. Cut only from a SHA with both while it remains in current main history; the stable publish refuses a cut commit without both. A minor cut additionally requires Cindy, the release owner, to explicitly sign off on the exact vX.Y.0 immediately before the branch is created; scheduled or standing authority never substitutes for that sign-off.

  2. Create the single marked release/vX.Y.Z branch. Its version is the fixed-group version declared by the cut commit. The marker and plan freeze the cut SHA, Changeset paths and hashes, branch identity, and plan digest.

  3. On that branch, run pnpm version-packages. It admits the frozen Changesets against the declared tier, writes changelogs under that already-declared version, promotes staged codemods, refreshes exact internal pins, and deletes only the frozen Changesets. It never chooses or bumps the version. Refresh and verify the lockfile before the Version Packages PR merges.

  4. Clear the public editorial gate on the generated PR before it merges, so a failed criterion is fixed on that PR rather than by moving the release head afterwards. For a patch, self-grade the complete generated changelogs and draft GitHub Release notes against the public Blog Review Rubric under the update profile, record the result on the PR, and fix and re-grade every failed criterion. A minor requires Cindy's explicit human editorial approval of the changelogs, release notes, and required public blog, recorded the same way. Then merge the generated PR to the release branch, run exact-head branch CI, and tag and publish that exact branch head. Stable publication from main is refused.

    After that generated PR, the branch admits one additional class only when its exact gate exposes a test or harness defect: one commit whose stable patch id and exact changed-line digest equal a non-merge commit still present in main, and whose changed files are only non-docsite tests or internal/interaction-harness/. It may not change product code, packages, Changesets, assertions, test controls, timeouts, retries, or snapshots. The rule that admits it must first land on main through normal review and CI. If the active branch predates that rule, the release owner appends one normal fast-forward policy sync after validate-policy-carry proves that the policy-only file set and resulting contents exactly equal the branch-specific bundle reviewed in the validator commit already merged on main. The bundle starts from the active release head. It carries this validator and scope change plus the existing undecided-scope contract fallback that treats every file as changed when GitHub truncates the file list; it carries no other later main workflow or product work. The sync is not a pull request, uses no force or admin operation, marks no check, and grants no release state. For v0.7.12 only, if normal CI on that sync proves the carried validator incomplete or finds that the carried fallback lacks its matching workflow-contract test, one second and final reviewed fast-forward may follow. Its exact bundle changes only active-release.mjs, its test, and .github/scripts/touched-components.test.mjs; every line is an exact port from a normal pull request already merged on main; and CodeBunny approves the corrective commit's exact head before the fast-forward. The full release gate reruns at that head. No third sync is allowed. The repair branch then rebases onto the final release head, and its required checks run under that trusted base. The repair itself needs exact-head CodeBunny approval and every normal product and test lane; after merge, the full exact-head release gate runs again and must pass. No retry, skipped check, admin merge, or manual override replaces these proofs.

  5. Squash the published branch outputs back into current main through chore/merge-vX.Y.Z-to-main. The trusted validator requires the immutable tag, active branch head, and plan digest; exact generated bytes and frozen deletions; and preservation of every post-cut Changeset, commit, unrelated field, and main's current version declaration. Branch lifecycle files never land on main.

  6. In a separate owner PR, declare the next plan across the fixed-group versions, exact internal pins, and lockfile. The released version's patch successor is the default. A minor successor is used only when the owner explicitly names it.

After a cut, main's declaration remains its future plan and may change independently of the frozen release branch. Required pull-request lint does not compare it with the cut or newest stable tag. Canary publication owns that ordering boundary: it publishes only from one plain declaration above stable, skips equality, and fails below-stable or split declarations. Trusted merge-back preserves main's declaration; the separate next-plan PR advances it after the release.

Changesets and codemods

Feature PRs add normal Changesets with pnpm changeset:new. Pending Changesets do not choose the release version. While packages are 0.x, [breaking] work is admissible only when main already declares the next minor; a patch declaration refuses it. A PR that lowers a minor plan to a patch is itself refused while a [breaking] Changeset is pending.

Core codemods for unreleased changes are staged in packages/cli/assets/codemods/transforms/next/. During the Version Packages PR, pnpm version-packages runs scripts/promote-codemod-next.mjs after changelogs are written. It copies every staged entry except README.md into transforms/v<declared-version>/, clears the promoted files from next, and updates the registry. Review those generated files with the changelogs.

Stable and canary publication

Both publication paths live in .github/workflows/release.yml, because npm permits one trusted GitHub workflow per package.

  • Stable: explicit dispatch from the immutable vX.Y.Z tag with the exact release branch, version, head, tag, and plan digest. It publishes latest.
  • Canary: at most hourly from main's tip, or on demand from main (a dispatch with channel: canary). It publishes <declared-version>-canary.<short-sha> to canary only while the declaration is strictly above the newest stable tag. It never authorizes or mutates stable release state.

The publish step uses pnpm-native publishing:

pnpm publish ./packages/<package> \
  --tag latest --provenance --access public --no-git-checks

Trusted-publisher setup

Trust is configured per package. It must name release.yml and allow direct npm publish. A new public package must exist on npm before trust can be registered, so once per new package an npm organization owner runs, in their own terminal (npm opens two-factor prompts in the browser that only the owner can complete):

npm i -g npm@latest
npm --version   # 11.15 or later
npm login --registry https://registry.npmjs.org
node scripts/npm/setup-trusted-publishing.mjs
node scripts/npm/setup-trusted-publishing.mjs \
  --bootstrap --setup-trust --workflow release.yml
  • The default invocation is audit-only.
  • --bootstrap claims a missing package name with a deprecated 0.0.0-bootstrap.0 placeholder under the bootstrap dist-tag. npm makes a package's first version its latest, so a plain install of the package resolves to the empty placeholder until the package's first stable release.
  • --setup-trust registers release.yml for meta/astryx with direct publish allowed. The script refuses npm older than 11.15: older npm ignores the publish permission, creating a publisher that can only stage releases, and lists every existing publisher as a conflict.
  • Use --replace only when an existing trust record is intentionally being replaced, never to clear a conflict reported by npm older than 11.15.

Then open the package's trusted-publisher settings on npmjs.com (https://www.npmjs.com/package/<name>/access) and confirm the meta/astryx release.yml entry allows npm publish, not only npm stage publish. The same page is the manual path when the script cannot finish: add a GitHub Actions publisher with owner meta, repository astryx, workflow release.yml, no environment, and npm publish allowed.

npm expires a new trusted publisher that no publish has validated within 48 hours. The next canary (the hourly run, or a canary dispatch from main) publishes the package's canary and validates it. If no canary publishes in that window, recreate the publisher.

Registry reads can keep reporting a just-created package as missing for a few minutes. A re-run of --bootstrap in that window gets 409 for the placeholder version; the name is already claimed, and the script continues to trust setup.

The repo pins pnpm 11. The CI Node line must bundle npm 11.5.1 or later for OIDC publishing; the local trust setup command requires npm 11.15 or later.