Releasing @insforge/ui
A GitHub Release tagged v<version> triggers .github/workflows/publish.yml. The workflow authenticates with npm trusted publishing: GitHub issues an OIDC token for the run, npm checks it against the trusted publisher registered for the package, and the publish carries provenance. No npm token exists in this repository, its secrets, or any maintainer's environment, and none should be added.
One-Time Setup on npmjs.com
Done once by a package maintainer, at https://www.npmjs.com/package/@insforge/ui/access → Trusted Publisher → GitHub Actions:
| Field |
Value |
| Organization or user |
InsForge |
| Repository |
UI |
| Workflow filename |
publish.yml |
| Environment name |
leave empty |
The four values must match the workflow exactly. Renaming the repository or the workflow file breaks publishing until the npm side is updated. Creating a Release requires write access to the repository, and that is the whole access control for publishing.
Cut a Release
On a branch, bump the version and the lockfile together:
npm version <patch|minor|major> --no-git-tag-version
Open a PR, merge to main, wait for the CI run on main to be green.
Create the Release. The tag is v plus the exact package.json version:
gh release create v<version> --target main --generate-notes
Tick pre-release only for a version with a prerelease suffix (0.2.0-beta.1); pre-releases publish under the next dist-tag instead of latest. Drafts do not trigger anything until published.
Watch the run and read the authoritative conclusion afterwards (gh run watch can exit non-zero for reasons other than failure):
gh run list --workflow publish.yml --limit 1
gh run watch <run-id> --exit-status
gh run view <run-id>
Verify on npm:
npm view @insforge/ui version dist-tags
The package page shows a Provenance section linking back to the workflow run.
Move consumers forward: bump the @insforge/ui range in the InsForge monorepo (packages/dashboard/package.json) and in insforge-cloud (package.json), then run npm install there.
When the Workflow Fails
- "package.json is at X but the release tag is vY" — tag and version disagree. Bump to a new version and cut a fresh release; do not reuse the tag.
- "already on npm" — that version exists. npm never accepts a republish, so bump.
ENEEDAUTH, E401, E404, or "Unable to authenticate" at npm publish — the trusted publisher on npmjs.com does not match the run (owner, repository, workflow filename, environment), or npm on the runner is older than 11.5.1. The workflow prints npm --version right after upgrading; check it.- lint, typecheck, or test failed — the release ran ahead of CI. Fix on
main, bump, release again.
- A failed run leaves nothing on npm. Re-running the same release is safe until the publish step has succeeded once.
Rules
Publish only through the workflow. A laptop publish has no provenance and skips the checks.
Never add an npm token to the repository, its secrets, or the workflow.
Versions are immutable. To retract a bad release, publish a fixed version and deprecate the bad one:
npm deprecate @insforge/ui@<bad-version> "use <fixed-version>"
Deprecation is a manual maintainer action against npm and is the only step in this process that uses a personal login.
1---2name: release3description: Use this skill to publish a new version of @insforge/ui to npm from the InsForge/UI repository, or to diagnose a publish that failed. Publishing runs only through GitHub Actions with npm trusted publishing; there is no token to find.4---56# Releasing @insforge/ui78A GitHub Release tagged `v<version>` triggers `.github/workflows/publish.yml`. The workflow authenticates with npm trusted publishing: GitHub issues an OIDC token for the run, npm checks it against the trusted publisher registered for the package, and the publish carries provenance. No npm token exists in this repository, its secrets, or any maintainer's environment, and none should be added.910## One-Time Setup on npmjs.com1112Done once by a package maintainer, at https://www.npmjs.com/package/@insforge/ui/access → Trusted Publisher → GitHub Actions:1314| Field | Value |15| --- | --- |16| Organization or user | `InsForge` |17| Repository | `UI` |18| Workflow filename | `publish.yml` |19| Environment name | leave empty |2021The four values must match the workflow exactly. Renaming the repository or the workflow file breaks publishing until the npm side is updated. Creating a Release requires write access to the repository, and that is the whole access control for publishing.2223## Cut a Release24251. On a branch, bump the version and the lockfile together:2627 ```bash28 npm version <patch|minor|major> --no-git-tag-version29 ```3031 Open a PR, merge to `main`, wait for the CI run on `main` to be green.32332. Create the Release. The tag is `v` plus the exact `package.json` version:3435 ```bash36 gh release create v<version> --target main --generate-notes37 ```3839 Tick pre-release only for a version with a prerelease suffix (`0.2.0-beta.1`); pre-releases publish under the `next` dist-tag instead of `latest`. Drafts do not trigger anything until published.40413. Watch the run and read the authoritative conclusion afterwards (`gh run watch` can exit non-zero for reasons other than failure):4243 ```bash44 gh run list --workflow publish.yml --limit 145 gh run watch <run-id> --exit-status46 gh run view <run-id>47 ```48494. Verify on npm:5051 ```bash52 npm view @insforge/ui version dist-tags53 ```5455 The package page shows a Provenance section linking back to the workflow run.56575. Move consumers forward: bump the `@insforge/ui` range in the InsForge monorepo (`packages/dashboard/package.json`) and in insforge-cloud (`package.json`), then run `npm install` there.5859## When the Workflow Fails6061- **"package.json is at X but the release tag is vY"** — tag and version disagree. Bump to a new version and cut a fresh release; do not reuse the tag.62- **"already on npm"** — that version exists. npm never accepts a republish, so bump.63- **`ENEEDAUTH`, `E401`, `E404`, or "Unable to authenticate" at `npm publish`** — the trusted publisher on npmjs.com does not match the run (owner, repository, workflow filename, environment), or npm on the runner is older than 11.5.1. The workflow prints `npm --version` right after upgrading; check it.64- **lint, typecheck, or test failed** — the release ran ahead of CI. Fix on `main`, bump, release again.65- A failed run leaves nothing on npm. Re-running the same release is safe until the publish step has succeeded once.6667## Rules6869- Publish only through the workflow. A laptop publish has no provenance and skips the checks.70- Never add an npm token to the repository, its secrets, or the workflow.71- Versions are immutable. To retract a bad release, publish a fixed version and deprecate the bad one:7273 ```bash74 npm deprecate @insforge/ui@<bad-version> "use <fixed-version>"75 ```7677 Deprecation is a manual maintainer action against npm and is the only step in this process that uses a personal login.
insforge