setup-npm-trusted-publish

setup-npm-trusted-publish

A tool to setup OIDC (OpenID Connect) trusted publishing for npm packages.

It publishes a minimal placeholder package so you can configure OIDC trusted publishing on npmjs.com afterwards.

Background

Unlike PyPI which allows configuring OIDC for not-yet-existing packages, npm requires a package to exist before you can configure trusted publishing. This tool helps work around that limitation by creating and publishing a minimal placeholder package.

See:

• GitHub Community Discussion #127011
• Allow publishing initial version with OIDC · Issue #8544 · npm/cli

Installation

npm install -g setup-npm-trusted-publish

Or run directly with npx:

npx setup-npm-trusted-publish <package-name>

Usage

setup-npm-trusted-publish <package-name>

Options:

• --dry-run - Create the package but don't publish
• --access <public|restricted> - Access level for scoped packages (default: public)
• --registry <url> - npm registry URL (default: https://registry.npmjs.org)

Environment Variables:

• NPM_TOKEN - npm authentication token for users who don't have npm login configured locally. If set, a temporary .npmrc is created in the package directory with //registry.npmjs.org/:_authToken=${NPM_TOKEN}. npm expands ${NPM_TOKEN} at runtime, so the actual token is never written to disk. The .npmrc is cleaned up with the temporary directory after publishing.

Examples:

setup-npm-trusted-publish my-package
setup-npm-trusted-publish @myorg/my-package
read -s NPM_TOKEN && export NPM_TOKEN && setup-npm-trusted-publish my-package
setup-npm-trusted-publish my-package --dry-run
setup-npm-trusted-publish my-package --registry https://npm.example.com

After publishing, configure OIDC trusted publishing and publishing MFA requirement (mfa=automation / mfa=publish) on npmjs.com under https://www.npmjs.com/package/<package-name>/access. Both npm trust and npm access set mfa=... require interactive 2FA OTP and cannot be driven by NPM_TOKEN (see "Why not use npm trust or npm access set mfa=...?" below for details), so they are intentionally not part of this CLI.

Usage without local npm login

If you don't have npm login configured locally, you can use a one-time Granular Access Token:

• Go to https://www.npmjs.com/settings/{user}/tokens and create a new Granular Access Token
• Configure the token:
  • Packages and scopes: Read and write (select the target scope if publishing a scoped package)
  • Expiration: 7 days (shortest available, since this is one-time use)
• Publish using the token:

  read -s NPM_TOKEN && export NPM_TOKEN && setup-npm-trusted-publish @myorg/my-package
  

• Revoke the token at https://www.npmjs.com/settings/{user}/tokens after publishing

What it does

• Creates a minimal npm package in a temporary directory
• Generates a package.json with basic metadata for OIDC setup
• Creates a README.md that clearly states the package is for OIDC setup only
• Automatically publishes the package to npm
• Cleans up the temporary directory
• Provides a direct link to configure OIDC at https://www.npmjs.com/package/<package-name>/access

The generated README explicitly indicates:

• The package is NOT functional
• It contains NO code
• It exists ONLY for OIDC configuration
• It should NOT be used as a dependency

Why not use npm trust or npm access set mfa=...?

npm 11.10.0+ provides an npm trust command that can configure trusted publishing without publishing a placeholder. However, it has a significant limitation that makes it unsuitable for this tool's automation use case:

Granular Access Tokens (GAT) with the bypass 2FA option are not supported. Legacy basic auth (username and password) credentials will not work for trust commands or endpoints. Two-factor authentication must be enabled at the account level.

— npm-trust documentation

npm access set mfa=publish|automation falls back to the same web auth flow and rejects token-based execution with 401 token is invalid (npm/cli#9268, #8869).

In short, both commands require interactive 2FA OTP and cannot be driven by NPM_TOKEN (automation token / GAT with bypass 2FA). For non-interactive setup flows that this CLI targets, the placeholder publish + manual web UI configuration is the only reliable path. If those commands work for you interactively, run them directly without this tool.

Workflow

• Run this tool to create and publish a placeholder package
• Visit the provided URL (https://www.npmjs.com/package/<package-name>/access) to configure OIDC trusted publishing
• Set up your CI/CD workflow to publish the real package version with OIDC

Example Output

$ setup-npm-trusted-publish @myorg/my-package

📦 Creating placeholder package: @myorg/my-package
📁 Temp directory: /tmp/npm-oidc-setup-abc123def456
✅ Created placeholder package files

📤 Publishing package to npm...

✅ Successfully published: @myorg/my-package

🔗 View your package at: https://www.npmjs.com/package/@myorg/my-package

Next steps:
1. Go to https://www.npmjs.com/package/@myorg/my-package/access
2. Configure OIDC trusted publishing
3. Set up your CI/CD workflow to publish with OIDC

🧹 Cleaned up temp directory

Why is this needed?

npm's current implementation requires a package to exist before you can:

• Configure OIDC trusted publishing
• Generate granular access tokens

This tool provides a responsible way to "reserve" a package name for OIDC setup by creating a package that:

• Clearly communicates its purpose
• Cannot be mistaken for a functional package
• Enables the OIDC configuration workflow

Important Notes

• This tool is specifically for OIDC setup, not for name squatting
• The generated packages clearly indicate they are placeholders
• Always follow npm's policies and best practices
• Replace the placeholder with your actual package as soon as possible

License

MIT