# Set Up npm Trusted Publishing for a Node.js Package

Yes. An agent adds a release workflow that publishes your npm package with trusted publishing and provenance, proves it with a dry run, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-npm-trusted-publishing/nodejs/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the package is built, tested and published today. In a package like debug-js/debug, `package.json` is at version 4.4.3 with a `files` list of `src`, `LICENSE` and `README.md`, `main` at `./src/index.js` and `browser` at `./src/browser.js`, one dependency, `ms ^2.1.3`, and `engines.node >=6.0`. The scripts are `lint` with xo, `test:node` running Mocha over `test.js` and `test.node.js`, `test:browser` running Karma once in headless Chrome through browserify, and `test` chaining all three. There is no `.github` directory at all; `.travis.yml` is the only CI, on Node 6 through 11, and it never publishes. `.gitignore` lists `package-lock.json` and `yarn.lock`, so there is no lockfile and `npm ci` cannot be used. Nothing in the repository holds or references an npm token, which is the point: a trusted publisher needs none.

It writes `.github/workflows/release.yml` that runs when a GitHub release is published. The job sets `permissions` to `id-token: write` and `contents: read`, checks out the tag, and uses `actions/setup-node` with `registry-url` pointing at the npm registry and a Node version whose bundled npm supports trusted publishing, which it confirms by running `npm --version` in the job and in the sandbox; where the bundled npm is too old it adds a step that installs a current npm first. It runs `npm install`, then `npm run lint` and `npm run test:node`; it runs the Karma browser tests as well when the runner has Chrome, and says so if it leaves them out. A guard step compares the tag with `package.json`'s `version` field and fails the job when they differ, so a release tagged `v4.4.4` cannot publish 4.4.3. The last step is `npm publish --provenance --access public`, with no `NODE_AUTH_TOKEN`: npm exchanges the job's OIDC token for a short-lived publish token and attaches a provenance statement that names this repository, workflow and commit.

It adds a short Releasing section to the README with the one-time step a maintainer does on npmjs.com, under the package's settings: add a trusted publisher of type GitHub Actions with the repository owner, the repository name and the workflow file name `release.yml`, and an environment name only if the workflow uses one. It also adds `publishConfig.provenance` to `package.json` so a manual `npm publish` from a supported CI carries provenance too, and keeps the tag pattern the guard expects documented in the same section.

In its sandbox it runs `npm install`, `npm run lint` and `npm run test:node`, and installs Chromium to try `npm run test:browser` so the pull request says which Node versions the old Mocha and Karma still run on. It runs `npm pack --dry-run` to list exactly what the `files` field ships, which should be `src/`, the licence, the README and `package.json`, and `npm publish --dry-run` to show the registry call the workflow would make. It lints the workflow with `actionlint`. Nothing is published: the workflow runs only on a published release and the sandbox has no OIDC token.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Set up npm trusted publishing with provenance for this package and open a pull request. Read package.json, .gitignore, .travis.yml, karma.conf.js, test.js, test.node.js and the files under src first. Write .github/workflows/release.yml that runs when a GitHub release is published: permissions id-token write and contents read, checkout, setup-node with registry-url set to the npm registry and a Node whose npm supports trusted publishing, npm install since the repository ignores lockfiles, npm run lint, npm run test:node, a guard that fails when the tag does not match the version in package.json, then npm publish --provenance --access public with no token. Add publishConfig.provenance to package.json and a Releasing section in the README that explains the one-time trusted publisher setup on npmjs.com with the workflow file name. In the sandbox run the tests, npm pack --dry-run, npm publish --dry-run and actionlint, and keep the output. Do not publish anything and do not create a tag. Open a pull request that lists the files the package would ship and the exact npmjs.com settings to enter.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds `.github/workflows/release.yml`, adds `publishConfig` to `package.json`, and adds a Releasing section to `README.md`. The description quotes the `npm pack --dry-run` listing of files, the `npm publish --dry-run` output, the lint and Mocha output on the Node version the workflow uses, the `actionlint` result, and the trusted publisher fields to enter on npmjs.com, with the repository and workflow file name filled in.

Before merging, a reviewer checks the tag convention the guard expects, whether publishing should wait on a protected environment with required reviewers, and whether the browser tests belong in the release job. The first real publish happens only after a maintainer adds the trusted publisher on npmjs.com and publishes a release, and its provenance then shows on the package page.

## Run it on every npm package published with a long-lived token

A maintainer of several packages sends one `POST /o/{org}/sessions` per repository, this prompt and the repository in `resources`. `GET /o/{org}/github` lists every repository the Rush GitHub App installation can reach, so a script can start a run for each one with a `package.json` that is not `private` and no workflow that publishes. Each run reads that package's own scripts, `files` list and lockfile situation, so a package with `npm ci` and a build step gets those in its job, and each opens its own pull request.

Set a webhook URL on the API key and Rush posts `run.completed` or `run.failed` when a run's turn finishes, with `session_url` so your server can read the pull request link. Send a fresh UUID as `request_id` with each request so a retry returns the run already started.

## Why run it on Rush?

A publish workflow is the one job nobody wants to debug on the day of a release, and it is hard to test without publishing. On Rush the agent gets as close as the registry allows in its own sandbox: it runs the tests on the Node the workflow will use, lists what `npm pack` would ship, runs `npm publish --dry-run` and lints the workflow, and every output stays in the run's record beside the diff, so the review is about the release policy rather than about whether the YAML is right.

Trusted publishing removes the long-lived token from secrets, and provenance lets anyone installing the package verify which commit and workflow built it. The same request sets this up for every package a team maintains, one run and one pull request each, with no token ever pasted into a settings page.

## Frequently asked questions

### Do I still need an NPM_TOKEN secret?

No. With a trusted publisher configured on npmjs.com, the job's OIDC token is exchanged for a short-lived publish token at publish time. The workflow sets `id-token: write` and never reads a secret, and an old automation token can be revoked once the first release goes through.

### Why run the workflow on a published release rather than on a tag push?

Because a release has notes and a visible author, and publishing it is a deliberate click. The guard step still compares the release tag with `package.json` so a mistyped tag fails before anything reaches the registry. If you prefer tag pushes, say so and the trigger changes.

### What about the Travis configuration and the old Node versions?

The agent leaves `.travis.yml` alone, since the issue is publishing, and reports which Node versions the Mocha and Karma suites still pass on in the sandbox. Replacing Travis with a test workflow is a separate change you can ask for in a follow-up message.

### Does the lack of a lockfile matter?

It means the release job runs `npm install` and resolves the devDependencies fresh each time, which the pull request points out. Provenance covers the package you publish, not the tools that tested it; committing a lockfile would make the test step reproducible and is a decision for the maintainers.

## More Node.js jobs

- [Add Rate Limiting to a Node.js Login Route](https://getrush.ai/run/add-rate-limiting/nodejs/)
- [Add Security Headers to a Node.js App](https://getrush.ai/run/add-security-headers/nodejs/)
- [Add Structured Logging to a Node.js App from a Linear Issue](https://getrush.ai/run/add-structured-logging/nodejs/)

## The same job on other stacks

- [Publish a TypeScript Library to npm With Trusted Publishing](https://getrush.ai/run/add-npm-trusted-publishing/typescript-library/)

## More jobs like this: Hand off a long task

- [Add NuGet Lock Files to a .NET Solution](https://getrush.ai/run/add-nuget-lock-files/dotnet/)
- [Add an OAuth Install Flow to a Slack Bolt App](https://getrush.ai/run/add-oauth-install-flow/slack-bolt/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
