Missing guidance for first-time package publishing with Trusted Publishers (OIDC)
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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