release

name	release
description	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.

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

1. 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.

2. 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.

3. 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>
   

4. Verify on npm:

   npm view @insforge/ui version dist-tags
   

   The package page shows a Provenance section linking back to the workflow run.

5. 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.