npm-publish

Files (1)

• SKILL.md

SKILL.md (first lines)

# npm publish

## Pick the route

| Route | When | Credential |
|---|---|---|
| **1. Trusted publishing** (preferred) | package source on GitHub/GitLab | none stored: CI exchanges an OIDC token with npm |
| 2. Granular token, "bypass 2FA" | quick one-off from a shell, **until ~January 2027** | `NPM_TOKEN` in the environment |
| 3. Interactive | anything else, and after the deprecation | `npm login` + 2FA code |

Why: GitHub changelog 2026-07-08 ("npm install-time security and GAT bypass2FA
deprecation"). Bypass-2FA granular tokens lost their 2FA bypass for account/package
management in August 2026 and lose **direct publishing around January 2027**. After that,
their publishes are only staged until a human approves with 2FA.

## 1. Trusted publishing

1. Add `.github/workflows/publish.yml`: trigger `push: tags: ["v*"]`, `permissions:
   id-token: write`, `actions/setup-node` with `registry-url: https://registry.npmjs.org`,
   **npm ≥ 11.5.1** (`npm install -g npm@latest`), then `npm ci`, build, `npm publish`.
   Check that the tag matches `package.json` version. Provenance is attached automatically.
2. One-time, by the package owner on npmjs.com: package → Settings → **Trusted publisher** →
   GitHub Actions → owner, repository, workflow file name. (The package must already exist;
   publish the first version by route 2 or 3.)
3. Release: bump `version`, commit, `git tag vX.Y.Z && git push --tags`. Verify with
   `npm view <name> version` and the workflow run, not by assuming.

## 2. Token in `NPM_TOKEN` (until ~Jan 2027)

Granular token: read+write, limited packages, "bypass 2FA", expiry. Run under whatever
injects `NPM_TOKEN` for one command; never write it to `~/.npmrc` or the repo:

```bash
bash -c '
  [ -n "$NPM_TOKEN" ] || { echo "NPM_TOKEN missing"; exit 1; }
  cfg=$(mktemp); trap "rm -f $cfg" EXIT; chmod 600 "$cfg"
  printf "//registry.npmjs.org/:_authToken=%s\n" "$NPM_TOKEN" > "$cfg"
  NPM_CONFIG_USERCONFIG="$cfg" npm whoami && NPM_CONFIG_USERCONFIG="$cfg" npm publish'
```

## 3. Interactive

`npm login` (user runs it, e.g. `! npm login`), then `npm publish --otp=<code>` with the code
fetched immediately before (codes expire in ~30 s).

## Always

- Check the registry first (`npm view <name> version`). Publishing an existing version fails.
- Scoped packages without `publishConfig.access`: add `--access public`.
- Verify on the registry afterwards; push the commit and tag.

| Symptom | Meaning |
|---|---|
| `E401` on `whoami` | token expired or revoked |
| `EOTP` | token lacks bypass-2FA (or the bypass no longer applies). Use route 1 or 3 |
| `E403 … cannot publish over` | version exists. Bump |
| CI: `ENEEDAUTH` / 404 on publish | trusted publisher not configured, wrong workflow filename, or npm < 11.5.1 |

From danielrosehill/Linux-Packaging-Plugin, MIT.

More from danielrosehill/Linux-Packaging-Plugin