An open source design system that's fully customizable and agent ready
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
Run the canonical full-scope
release-checkon an exact commit from currentmain. 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 withshaset to the checked commit, which tests exactly that commit; a dispatch withoutshatests whatever is main's tip when it starts and is no receipt. Cut only from a SHA with both while it remains in currentmainhistory; the stable publish refuses a cut commit without both. A minor cut additionally requires Cindy, the release owner, to explicitly sign off on the exactvX.Y.0immediately before the branch is created; scheduled or standing authority never substitutes for that sign-off.Create the single marked
release/vX.Y.Zbranch. 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.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.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
updateprofile, 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 frommainis 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 orinternal/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 onmainthrough normal review and CI. If the active branch predates that rule, the release owner appends one normal fast-forward policy sync aftervalidate-policy-carryproves that the policy-only file set and resulting contents exactly equal the branch-specific bundle reviewed in the validator commit already merged onmain. 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 latermainworkflow or product work. The sync is not a pull request, uses no force or admin operation, marks no check, and grants no release state. Forv0.7.12only, 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 onlyactive-release.mjs, its test, and.github/scripts/touched-components.test.mjs; every line is an exact port from a normal pull request already merged onmain; 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.Squash the published branch outputs back into current
mainthroughchore/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 onmain.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.Ztag with the exact release branch, version, head, tag, and plan digest. It publisheslatest. - Canary: at most hourly from main's tip, or on demand from
main(a dispatch withchannel: canary). It publishes<declared-version>-canary.<short-sha>tocanaryonly 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.
--bootstrapclaims a missing package name with a deprecated0.0.0-bootstrap.0placeholder under thebootstrapdist-tag. npm makes a package's first version itslatest, so a plain install of the package resolves to the empty placeholder until the package's first stable release.--setup-trustregistersrelease.ymlformeta/astryxwith 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
--replaceonly 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.