Post hero imagePost hero image

@aardarch/aardink-web publishes from GitHub Actions through npm trusted publishing. There is no NPM_TOKEN secret in the repository, in an environment, or on my machine. The @sjohansson packages in astro-components work the same way.

A leaked token is the usual way a package gets hijacked. A token that does not exist cannot leak. That is the whole pitch, and it costs about half an hour once.

How it works

The workflow asks GitHub for a short-lived OIDC token that says “I am this workflow, in this repository, running in this environment”. npm checks that against the trusted publisher configured on the package. If it matches, npm hands back a publish credential that lasts for that one job.

Nothing is stored. Nothing needs rotating. Provenance comes along too, so the package page shows which commit and workflow built it.

The first version goes up by hand

npm only lets you attach a trusted publisher to a package that already exists. So the first version cannot come from CI. You publish it from your machine, then configure trust straight afterwards.

The steps, for a new package:

  1. Make sure the npm account has two-factor authentication turned on. Publishing and the trust setup both ask for it.
  2. For a scoped package, create the org first. I made aardarch on the free plan, which allows unlimited public packages. The scope has to match the name already in your code.
  3. Run npm login, approve in the browser, then npm whoami and npm org ls aardarch to check you are an owner.
  4. Build the package and check it with npm pack --dry-run before you publish anything.
  5. Run npm publish --access public, approving with 2FA when asked.

I published 0.5.0 this way on 27 September 2026. I built it from a separate git worktree of the v0.5.0 tag, so it did not touch the branch I was working on. That worktree needed a copy of local.properties, because Gradle configures the Android modules even for a wasm-only task.

Two things bit me:

  • Scoped packages default to private, and npm rejects a private scoped package on the free plan. The 0.5.0 package.json had no publishConfig, so I had to pass --access public by hand. Without it you get a 402. Put publishConfig in the package from the start and later versions do not need the flag.
  • npm always includes README.md and LICENSE from the package folder. The 0.5.0 build had neither, so I copied them in before publishing. The dry run is where you notice.

Then check it landed. npm view @aardarch/aardink-web version dist-tags should show latest on 0.5.0.

Setting up the trust

Two places need configuring, and both have to agree.

On npm, add a trusted publisher for GitHub Actions. You can do it on the website under the package’s settings, or in one line from the terminal with npm 11.15 or later:

npm trust github @aardarch/aardink-web --file release.yml --repo aardarch/aardink --env npm --allow-publish --allow-stage-publish

The fields are the organisation, the repository, the workflow filename (the name only, no path), and the environment name. All four must match exactly. A near miss gives you a generic auth failure that does not say which field was wrong.

Don’t skip --allow-publish. Trusted publishers created since 3 September 2026 allow only staged publishing unless direct publishing is ticked, and the release workflow publishes directly.

Then lock the door. In the package’s publishing access settings, choose “Require two-factor authentication and disallow tokens”. From then on, only the workflow or a person with 2FA can publish. Run npm token list and revoke any old publish tokens while you are there.

On GitHub, create an environment called npm. Under deployment branches and tags, add a rule for tags matching v*. No secrets or variables go in it. The environment is half of the identity npm checks, and the tag rule means a stray branch cannot publish.

The workflow

The job that publishes is small once the build is done. The bits that matter:

publish-npm:
  runs-on: ubuntu-latest
  environment: npm
  permissions:
    contents: read
    id-token: write # the OIDC token npm exchanges for a short-lived publish credential
  steps:
    # ... checkout, build the package, smoke test it ...
    - uses: actions/setup-node@v7
      with:
        node-version: 24
        registry-url: "https://registry.npmjs.org"

    # Trusted publishing needs npm 11.5.1 or later.
    - name: Update npm
      run: npm install -g npm@latest

    - name: Publish
      working-directory: sample-web/build/npm
      run: |
        version="${GITHUB_REF_NAME#v}"
        if npm view "@aardarch/aardink-web@$version" version >/dev/null 2>&1; then
          echo "@aardarch/aardink-web@$version is already on npm; nothing to do."
          exit 0
        fi
        tag=latest
        case "$version" in *-*) tag=next;; esac
        npm publish --access public --tag "$tag"

id-token: write is what lets the job ask for the OIDC token. Without it you get ENEEDAUTH.

The npm install -g npm@latest step is not optional. Trusted publishing needs a recent npm, and the one bundled with some Node 24 images is too old.

The publish step does two jobs. A version with a hyphen in it, like 0.6.0-rc1, goes to the next dist-tag and never moves latest. And it skips a version that is already on npm, so re-running a failed release is safe.

Before that step, the job checks that the tag matches the version in package.json. A mismatch fails the build rather than publishing the wrong thing.

Staged publishing

If you want a human in the loop, set the repository variable NPM_PUBLISH_MODE to stage. The step then runs npm stage publish instead of npm publish. Nothing becomes public until a maintainer runs npm stage approve <stage-id> and answers a 2FA prompt. With that mode you can untick direct publishing in the trust settings, so even a compromised workflow can only stage a version, never release one.

I left it off. A release tag is already a deliberate act, and I did not want npm waiting on me when Maven Central does not.

Things that fail quietly

repository.url must be exactly git+https://github.com/aardarch/aardink.git. Anything else and npm rejects the provenance statement. The error does not point at the field.

A broken exports map or missing types will ship happily and fail in someone else’s bundler. The job runs publint and @arethetypeswrong/cli before it publishes, and the same two run in ordinary CI, so a bad package fails on a pull request instead of on a tag:

npm pack --dry-run
npx --yes publint@0.3 --strict
npx --yes @arethetypeswrong/cli@0.18 --pack --profile esm-only

The rest of the failures, in one place:

SymptomCause
402 on the manual publishThe scoped package defaulted to private. Pass --access public.
403 on the manual publishNot an owner of the scope, or 2FA was not approved.
ENEEDAUTH or a 404 on PUT in CIThe trusted publisher does not match, or id-token: write is missing.
Publish rejected although the OIDC login workedDirect publishing was not allowed on the trusted publisher. Only staging was.
The job waits on, or fails at, the environmentThe v* tag rule is missing from the npm environment.
Provenance rejectedrepository.url is not exactly the git+https URL.

The first automated publish was v0.6.0-rc1. It went to next with a provenance badge, and latest stayed on 0.5.0 until v0.6.0. She’ll be right from there: tag, wait, done.