---
title: "Agent Skill to Npm Trusted Publishing"
platform: "Promptally"
canonical_url: "https://app.promptally.dev/p/skill-npm-trusted-publishing"
modality: "SKILL"
category: "Fullstack & Backend Engineering"
compatible_models: [Universal / Model Agnostic]
access_tier: "Free Public Artifact (No Auth Required)"
license: "MIT"
---

# Agent Skill to Npm Trusted Publishing

**Summary:** Agent Skill to Npm Trusted Publishing is a verified SKILL blueprint on Promptally in Fullstack & Backend Engineering optimized for leading AI models. Set up or fix npm trusted publishing (OIDC) in GitHub Actions and remove NPM TOKEN. Use for ENEEDAUTH, E404 on PUT, E422 repository.url, or migrating off 2FA-bypass tokens before January 2027. Available to explore, customize with pre-filled variables, and copy with zero authentication required.

## Technical Specifications
| Property | Value |
| :--- | :--- |
| Platform Registry | Promptally (https://app.promptally.dev) |
| Modality | SKILL |
| Category | Fullstack & Backend Engineering |
| Compatible Engines | Universal / Model Agnostic |
| Dynamic Variables | None (Static Blueprint) |
| Approx. Token Length | 1,304 |
| Access Tier | Free Public Artifact (No Auth Required) |
| License | MIT |

### Pre-Filled Template & Production Source

````md
---
name: npm-trusted-publishing
description: Set up or fix npm trusted publishing (OIDC) in GitHub Actions and remove NPM_TOKEN. Use for ENEEDAUTH, E404 on PUT, E422 repository.url, or migrating off 2FA-bypass tokens before January 2027.
---

# npm Trusted Publishing

Moves a GitHub Actions release from a stored `NPM_TOKEN` to npm [trusted publishing](https://docs.npmjs.com/trusted-publishers). GitHub signs a short-lived OIDC token for the run, and npm exchanges it for a publish token. It also diagnoses the misleading errors a half-finished migration produces. From January 2027, granular tokens that bypass 2FA can no longer publish directly ([npm docs](https://docs.npmjs.com/about-access-tokens/)).

## When to Use This Skill

- The user wants to remove `NPM_TOKEN` / `NODE_AUTH_TOKEN` from a release workflow or set up OIDC or provenance publishing.
- A CI publish fails with `ENEEDAUTH`, `404 Not Found - PUT https://registry.npmjs.org/...` or `E422 ... repository.url`.
- Release logs show `npm notice npm tokens that bypass 2FA are being restricted`.

## Checklist (all must hold)

Work through every item. Missing any one of them produces the errors above.

1. **OIDC permission:** the publishing job has `permissions: id-token: write`. If the job had no `permissions` block, keep the scopes it needs, such as `contents: write` for tags and releases or `pull-requests: write` for changesets. Adding a block drops every scope you don't list.
2. **npm 11.5.1 or newer** runs the publish. Node 24 ships it. Node 22 ships npm 10, so add `npm install -g npm@^11.5.1` (or a newer pinned major) before publishing. pnpm 10 hands the publish to npm, so the same rule applies. Yarn Berry needs 4.10.3+.
3. **No token reaches the publish step.** Remove `NODE_AUTH_TOKEN`, `NPM_TOKEN` and `YARN_NPM_AUTH_TOKEN` from the step, the job and the workflow `env`, and delete script lines that write `_authToken` or `npmAuthToken`. npm tries OIDC first but falls back to a configured token, so a leftover token keeps the old credential in use. Keep a **read-only** token only on install steps that need private packages.
4. **`actions/setup-node` has `registry-url: https://registry.npmjs.org`.**
5. **`package.json` `repository.url` names the same GitHub repo**, for example `git+https://github.com/OWNER/REPO.git`, plus `directory` for workspace packages. A mismatch gives E422.
6. **A trusted publisher exists on npm for each package** (npmjs.com → package → Settings → Trusted publishing), or with npm 11.15+:
   `npm trust github <pkg> --repo OWNER/REPO --file release.yml --allow-publish --yes`
   - The workflow **file name** must match exactly; it is case-sensitive and includes `.yml`.
   - For a **reusable workflow**, use the *calling* workflow's file name, and grant `id-token: write` in the caller too.
   - If the job uses `environment:`, set the same environment on the publisher.
   - A package that doesn't exist yet must be published once by hand first.
7. **GitHub-hosted runner.** Self-hosted runners can't use trusted publishing.

## Security Rules

- **Untrusted triggers:** never add `id-token: write` to a job in a workflow triggered by `pull_request_target`, `issue_comment`, `workflow_run` or `discussion`. It would let outsiders exchange an OIDC token and publish. Move publishing to `release`, `push` (tags) or `workflow_dispatch`.
- **Dry runs:** `npm publish --dry-run` and `npm pack` jobs don't publish, so they need no `id-token` and no trusted publisher.
- **The old token:** delete the secret (`gh secret delete NPM_TOKEN`) and revoke it on npmjs.com only after the first tokenless release succeeds.

## Error Guide

| Error | Usual cause |
|---|---|
| `ENEEDAUTH` | No `id-token: write`, npm older than 11.5.1, or a workflow file name that doesn't match the trusted publisher |
| `404 Not Found - PUT https://registry.npmjs.org/<pkg>` | Same as above, a mismatched `environment`, no trusted publisher yet, or an expired token still being used |
| `E422 ... repository.url` | `repository` is missing in `package.json` or names another repo |
| Publish still uses the token | A token remains in env, `.npmrc` or `.yarnrc.yml` (checklist item 3) |

## Example

```yaml
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --access public   # no NODE_AUTH_TOKEN
```

## Automating It

[go-tokenless](https://github.com/Continuous-Actions/go-tokenless) (MIT) applies this checklist to an existing repository. Use it when the user wants the edits made for them.
- `npx go-tokenless` prints a read-only diff of the workflow and `package.json` changes, plus the `npm trust` commands.
- `npx go-tokenless apply` writes the changes.
- It refuses the unsafe cases above instead of guessing.

## Limitations

- The npm side (adding the trusted publisher, deleting the old token) needs the user's npm login with 2FA. Hand those steps to the user.
- Trusted publishing covers GitHub Actions, GitLab.com and CircleCI cloud only.

````

## Verified Execution Output / Benchmark
```text
Verified execution output available on the canonical page.
```

## Related Blueprints on Promptally
- [Agent Skill to Knowledge Ops](https://app.promptally.dev/p/skill-knowledge-ops)
- [Agent Skill to Content Hash Cache Pattern](https://app.promptally.dev/p/skill-content-hash-cache-pattern)
- [Agent Skill to Ck](https://app.promptally.dev/p/skill-ck)
- [Agent Skill to Swift Protocol Di Testing](https://app.promptally.dev/p/skill-swift-protocol-di-testing)
- [Agent Skill to Prisma Patterns](https://app.promptally.dev/p/skill-prisma-patterns)
- [Agent Skill to Agentic Engineering](https://app.promptally.dev/p/skill-agentic-engineering)
- [Agent Skill to Python Patterns](https://app.promptally.dev/p/skill-python-patterns)
- [Agent Skill to Docs Governance](https://app.promptally.dev/p/skill-docs-governance)