Skip to content

Release from GitHub with npm trusted publishing - #9

Merged
birazzzz merged 1 commit into
mainfrom
ci/trusted-publishing
Oct 21, 2026
Merged

birazzzz merged 1 commit into
mainfrom
ci/trusted-publishing

Conversation

@birazzzz

Copy link
Copy Markdown
Collaborator

What

Releases no longer need npm publish on a laptop.

.github/workflows/release.yml runs when a GitHub release is published:

  1. Stops if the release tag isn't v + the package.json version
  2. Installs, typechecks, installs Chromium, runs the tests
  3. npm stage publish through trusted publishing: npm trusts this workflow over OIDC, so no npm token is stored anywhere, and the version gets npm's provenance badge linking it to the commit
  4. Moves the major tag (v0) to the release, so uses: birazzzz/wrapguard@v0 gets it

The version is staged, not published: a maintainer approves it on npmjs.com (Staged Packages) with their two-factor login. That's what npm recommends for CI, and it means a compromised workflow still can't ship a version on its own.

Running the workflow by hand (Actions → Release → Run workflow) is a dry run: tests plus npm pack --dry-run, nothing published.

RELEASING.md: each release step by step, the one-time npm setup, and a checklist for launching the next open-source package with wrapguard as the template.

Requirements checked against npm's docs

  • Node 22.14+ and npm 11.5.1+ for trusted publishing, npm 11.15+ for npm stage: the workflow uses Node 24 and updates npm to ^11.15.0
  • id-token: write permission; contents: write for moving v0
  • GitHub-hosted runner (trusted publishing doesn't support self-hosted ones)
  • repository.url in package.json matches this repo

Checked locally

  • Workflow YAML parses (strict)
  • npm pack --dry-run: 29 files, 26.9 kB. (npm publish --dry-run refuses a version that's already on npm, which is always true between releases, so the dry run uses npm pack)

Not verified until it runs on GitHub: the OIDC exchange and npm stage publish. The first real test is the next release (0.2.0 with #8).

Before the first release through it

On npmjs.com: wrapguard → Settings → Trusted publishing → GitHub Actions, with birazzzz / wrapguard / release.yml, no environment, staging only.

- release.yml: on a published GitHub release, check the tag matches
  package.json, test, stage the version on npm through OIDC (no token),
  and move the major tag (v0). Run by hand for a dry run.
- Staged, not published: a maintainer approves on npmjs.com with 2FA.
- RELEASING.md: each release step by step, the one-time npm setup, and a
  checklist for launching the next open-source package from this template.
@birazzzz
birazzzz merged commit 11e6d31 into main Oct 21, 2026
3 checks passed
@birazzzz birazzzz mentioned this pull request Oct 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant