| name | secure-npm-package |
| description | Set up a secure release process for an npm package to protect it from supply chain attacks. Use for any request to create and publish a new npm package, secure npm publishing or releasing, set up npm Trusted Publishing, provenance, or Staged Publishing, harden a release workflow. |
Release an npm package securely
Set up a release process where no npm token exists to steal, releases can come only from one CI workflow, and every release still needs a manual approval with the maintainer's 2FA key.
How to run this skill
The setup is half repo files, half settings on npmjs.com and github.com that only the user can change. Present the manual settings first, before you touch any files — the settings are the part that needs the user, and if you do the repo changes first the instructions scroll past and get missed. For the settings, produce click-by-click instructions with direct links resolved from the repo's real data — package names from package.json, owner/repo from the repository field — and the exact values to enter. Wait for the user to confirm each block before verifying and moving on. Then, once the settings are handed off, do the repo files yourself. Never say "go to your package settings"; always give the resolved URL.
Step 1: Gather facts
Collect before changing anything:
- Packages. Read the root
package.json. If it has workspaces (or pnpm-workspace.yaml exists), it's a monorepo: enumerate every workspace package.json. Only packages without "private": true need npm settings.
- GitHub owner/repo. From the
repository field (normalize git+https://github.com/owner/repo.git, github:owner/repo, owner/repo), falling back to git remote get-url origin. If neither exists, ask the user, then add the repository field.
- Org or personal. Whether the owner is a GitHub organization or a user account (changes the 2FA instructions).
- Package manager and version. From the
packageManager field and lockfiles.
- Published or not.
npm view <name> version for each public package. An E404 means not yet published — see Not yet published packages.
- Tag format. Check existing version tags with
git tag --sort=-creatordate | head — some repos use v1.0.0, others 1.0.0, monorepos often <name>@1.0.0. Keep the existing format in the workflow trigger and release instructions; only if there are no tags yet, default to v1.0.0.
- Build step. Is there a
build script, and what directory does it emit?
- Existing workflows in
.github/workflows/, especially any current release workflow and any use of secrets.NPM_TOKEN.
Step 2: Manual settings (ask the user first)
Present these before changing any repo files, so the user doesn't miss them. Give a numbered checklist with resolved links and exact values, grouped by website. The workflow filename you reference below (publish.yaml) is the one you'll create in Step 3 — the name is fixed, so the user can set this up in parallel. After the user confirms, verify what you can (npm view <name>, gh api repos/<owner>/<repo>/rulesets if gh is authenticated) and re-ask about the rest.
On npmjs.com — for every public package
Repeat this block per package in a monorepo, each with its own link:
Open https://www.npmjs.com/package/<name>/access (you must be logged in as a maintainer).
- In Trusted Publisher select GitHub Actions and enter:
- Organization or user:
<owner>
- Repository:
<repo>
- Workflow filename:
publish.yaml
- Environment: leave empty
- Enable only Allow npm stage publish — deny plain
npm publish, so even hacked CI can't release without your approval.
- In Publishing access select Require two-factor authentication and disallow tokens. This revokes all existing tokens — warn me first if any other automation publishes this package with a token.
If the old setup used an NPM_TOKEN secret, also:
Delete the NPM_TOKEN secret at https://github.com/<owner>/<repo>/settings/secrets/actions and revoke the token itself at https://www.npmjs.com/settings/~/tokens.
On github.com
2FA for everyone. If the repo belongs to an organization:
Open https://github.com/organizations/<org>/settings/security and enable Require two-factor authentication under Authentication security.
For a personal account, ask the user to confirm 2FA is on at https://github.com/settings/security — prefer a hardware key or passkey.
Tag ruleset — with CI publishing, whoever can push a v* tag can trigger a release, so restrict tag creation:
Open https://github.com/<owner>/<repo>/settings/rules/new?target=tag and create:
- Ruleset Name:
Tags only by admins
- Enforcement status:
Active
- Bypass list: add
Repository admins
- Target tags:
Include all tags
- Tag rules: enable Restrict creations
Immutable releases — once a release is published, its tag and assets can never be changed or deleted, so an attacker can't silently swap artifacts under an existing version:
Open https://github.com/<owner>/<repo>/settings and in the Releases section enable Immutable releases.
Step 3: Repo changes (do these yourself)
Once the user is working through the settings, make the repo changes. Ask before overwriting an existing release workflow; carry over intentional extras (changelog generation, GitHub Releases) into separate jobs without id-token.
3a. .github/workflows/publish.yaml
The core rules, whatever the project's shape:
- Trigger on version tags, matching the repo's existing tag format (
v*, [0-9]*, …).
- The publish job installs no dependencies, uses no cache, and no third-party actions beyond checkout/setup-node/download-artifact. Anything running in a job with
id-token: write can publish the package.
- Build in a separate job, pass output via artifacts. Only the publish job gets
id-token: write; every job gets contents: read and persist-credentials: false on checkout.
--ignore-scripts on every install and on publish.npm stage publish, not npm publish — CI stages the release, a human approves it with 2FA.- Use
npm for the publish command even when the project uses pnpm, yarn, or bun. . The only exception is a project that genuinely needs its own package manager's staged-publish command (e.g. workspace: or beforePacking); there, use that tool's command instead.
- If there is no build script, drop the build job and the artifact steps entirely (best case — see Nano ID's workflow).
Template (adapt Node version, build output path, and install commands to the project's package manager, update versions to latest keeping SHA-commits pinning):
name: Release
on:
push:
tags:
- 'v*'
jobs:
test:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout the repository
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
with:
persist-credentials: false
- name: Install Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
with:
node-version: 26
cache: npm
- name: Install dependencies
run: npm ci --ignore-scripts
- name: Run tests
run: npm test
build:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout the repository
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
with:
persist-credentials: false
- name: Install Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
with:
node-version: 26
package-manager-cache: false
- name: Install dependencies
run: npm ci --ignore-scripts
- name: Build package
run: npm run build
- name: Upload build artifacts
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
with:
name: build-artifacts
path: dist/
retention-days: 1
publish:
runs-on: ubuntu-latest
needs:
- test
- build
permissions:
contents: read
id-token: write
steps:
- name: Checkout the repository
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
with:
persist-credentials: false
- name: Download build artifacts
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
with:
name: build-artifacts
path: dist/
- name: Install Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
with:
node-version: 26
package-manager-cache: false
- name: Publish npm package
run: npm stage publish --ignore-scripts
If an old workflow used secrets.NPM_TOKEN, remove it from the YAML now — deleting the secret and revoking the token is already covered by the Step 2 checklist (from the facts gathered in Step 1).
3b. Run zizmor locally and fix every finding
docker run --rm -t -v "$(pwd):/repo:ro" ghcr.io/zizmorcore/zizmor:latest /repo/.github/workflows
Run it yourself if Docker is available; otherwise ask the user to run this command and paste the output. Fix everything it reports in the existing workflows (pull_request_target misuse, shell injection, unpinned actions), then re-run until clean. Remind the user to delete stale branches that still contain old vulnerable workflows — attackers exploit old branches (that's how Nx was hit).
3c. .github/workflows/check-workflows.yaml — keep linting on CI
name: Lint CI workflows
on:
push:
branches: ['main']
pull_request:
branches: ['**']
jobs:
zizmor:
runs-on: ubuntu-latest
permissions:
contents: read
actions: read
steps:
- name: Checkout the repository
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
with:
persist-credentials: false
- name: Run zizmor
uses: zizmorcore/zizmor-action@6599ee8b7a49aef6a770f63d261d214911a7ce02
with:
advanced-security: false
3d. Dependency cooldown
Ask user what cooldown they prefer, the fast (1 day) or more secure (3 days). Use this fact:
A 3-day delay before adopting new dependency versions blocks ~94% of malicious releases (median takedown is 14 hours).
Apply the one matching the project's package manager:
npm config set --location=project min-release-age 3
pnpm config set --location=project minimumReleaseAge 4320
yarn config set npmMinimalAgeGate 3d
For bun, add to bunfig.toml:
[install]
minimumReleaseAge = 259200
pnpm 11+ already turns cooldown on — minimumReleaseAge defaults to 1440 (1 day). So on pnpm 11 you're only raising it to 3 days (4320).
3e. Make sure postinstall scripts are disabled locally
Dependency postinstall/preinstall scripts run arbitrary code on every developer machine. npm 12, pnpm 10, yarn 4.14, and bun disable them by default — check the version actually in use (packageManager field, npm --version etc.):
-
Version is new enough → nothing to add, just confirm.
-
Older → add an explicit config:
npm config set --location=project ignore-scripts true
yarn config set enableScripts false
Warn with npm's ignore-scripts=true: it also skips the project's own lifecycle scripts (prepare, husky hooks) — check nothing depends on them.
If some dependency genuinely needs its build script, allowlist that one package instead of re-enabling everything.
Not yet published packages
Trusted Publishing is configured on the package's npm settings page, which doesn't exist until the package is published. If npm view <name> returned E404:
- Check the name is actually free (an E404 with the registry reachable) and warn about typosquatting-adjacent names.
- The first release happens manually from the maintainer's machine:
npm publish --ignore-scripts (add --access public for a scoped package), authenticating interactively with 2FA. No token, no CI for this one release; it won't have the provenance badge — every later release will.
- Immediately after the first publish, run the full Step 2 checklist for the new package (Trusted Publisher, stage-only, disallow tokens).
- All later releases go through the tag → CI → staged approval flow.
In a monorepo, some packages may be published and others not — split the checklist accordingly.
Monorepo specifics
- npm settings are per package. Every public workspace package needs its own Trusted Publisher entry pointing at the same repo and the same
publish.yaml. Emit one settings link per package; missing one leaves that package unprotected.
- One publish workflow can release everything:
npm stage publish --ignore-scripts --workspaces, or --workspace=<name> per package if versions are tagged independently (adjust the tag trigger to the repo's scheme, e.g. <name>@*).
- Publish with
npm, unless the package relies on a pnpm-only feature npm can't reproduce — the workspace: protocol, or a beforePacking hook in .pnpmfile.cjs. Then publish with pnpm stage publish instead. In that case drop actions/setup-node from the publish job and let pnpm provide Node (use-node-version in pnpm-workspace.yaml) — one tool in the critical job, not two. First check the pnpm version supports staged/trusted publishing; if not, tell the user the tradeoff rather than silently downgrading security.
- The
--omit=dev hack. In a monorepo, keep build tools (compiler, bundler) in the root dependencies and test/lint tools in devDependencies, then install in the build job with npm ci --omit=dev --ignore-scripts — the build runs without linters, test runners, and their nested dependencies, shrinking the attack surface of the critical job. Moving packages between dependencies and devDependencies changes the published metadata, so ask the user before editing dependencies; on their yes, move the build tools and switch the build job's install to --omit=dev.
Tell the user how to release now
End by showing the new release flow, with the tag in the repo's detected format:
git add .
git commit -m 'Release 1.0.1 version'
git tag v1.0.1
git push origin v1.0.1
Then CI stages the release, and the user approves it in Staged Packages (npm user menu on npmjs.com) or with npm stage approve — this is the manual 2FA step that hacked CI can't fake. Suggest a patch release as an end-to-end test of the pipeline.
Suggest the next step: fewer dependencies
Every nested dependency is attack surface no setting can remove. After the setup is done, run:
npx @e18e/cli analyze
Show the user which dependency branches pull in the most nested packages, and offer to draft a plan (an issue or TODO) for replacing the biggest ones later with lighter alternatives — see the e18e replacements list — or with small local modules. Don't do the replacements now; it's a separate, larger task.
Final checklist
publish.yaml publishes with npm stage publish --ignore-scripts; only the publish job has id-token: write; no dependency installs or caches in it.- zizmor workflow added and existing workflows pass it; stale branches deleted.
- All actions pinned by SHA.
- Cooldown configured and dependency
postinstall scripts disabled (by version or by config).
- Every public package has a Trusted Publisher (stage-only) and tokens disallowed — confirmed by the user, per package.
- No
NPM_TOKEN left in workflows or repo secrets.
- Tag ruleset active; immutable releases enabled; 2FA required.
- User knows the tag → approve release flow and has run a test release.
