npm / npm/documentation

Missing guidance for first-time package publishing with Trusted Publishers (OIDC)

Open Beginner friendly
#1,926 3 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
MDX
Stars
711
Forks
4.2k
Avg merge
4d 16h
Merged PRs (30d)
3

Description

The documentation for npm Trusted Publishers (OIDC) at
https://docs.npmjs.com/trusted-publishers does not currently explain how to publish a package for the first time using this mechanism.

While the guide covers how to configure and use trusted publishing for existing packages, it lacks clarity on the initial publishing workflow.

In our case, attempting to publish a package for the first time using a GitHub Actions workflow with OIDC failed. The publish step did not succeed when the package did not yet exist on NPM.

As a workaround, we had to:

  • Perform the first publish manually (outside of OIDC / Trusted Publishers), this is something we would like to avoid
  • After the initial release existed on npm, subsequent releases using the GitHub Action with Trusted Publishers worked as expected

Documentation should explain how to handle first-time publishing with Trusted Publishers, including whether a manual initial publish is required.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the npm Trusted Publishers documentation at https://docs.npmjs.com/trusted-publishers and review its GitHub Actions/OIDC publishing guidance. Document the first-time publishing workflow, including whether a manual initial publish is required, and make the result clear for packages that do not yet exist on npm.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.