semantic-release / semantic-release/docs
Add recipe for publishing your first npm package with trusted publishing
Nobody has claimed this yet.
- Dominant language
- MDX
- Stars
- 5
- Forks
- 2
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 7
Description
During the discussion in #6, @travi shared a detailed workflow for bootstrapping new npm packages when using trusted publishing. This is a real-world gap in our documentation, the "Initial release" sections in our release-workflow recipes assume a frictionless first publish that doesn't reflect current npm constraints.
The problem
npm's trusted publishing doesn't support publishing the first version of a package. You must publish an initial version with a granular access token, configure trusted publishing in the npm web UI, and only then does the normal CI-based flow work. Our docs currently skip this step entirely.
Where to add it
All three release-workflow recipes already have an "Initial release" section:
- Publishing on distribution channels - "Initial release"
- Publishing pre-releases - "Initial release"
- Publishing maintenance releases - "Initial release"
These sections currently describe an idealized feat: initial commit → v1.0.0 flow. They're the natural place to add a callout or subsection covering the trusted-publishing bootstrap, since that's the exact moment users will encounter the constraint.
What to add
A concise addition to the "Initial release" sections covering:
- The constraint: npm trusted publishing requires at least one version published via a granular access token before it can be enabled
- The workaround: Using
npx semantic-release --no-cilocally for the initial publish - Security best practices: Short-lived tokens, minimal scope, prompt revocation
- The transition: Configure trusted publishing in npm settings after first publish, then all subsequent releases go through CI normally
This can be a shared callout/admonition component or a consistent paragraph added to each section or a new recipe page, likely added under Recipes > Release Workflow; and linked to these sections.
the reference workflow (from #6)
- Scaffold out a new package repo
- Push
mainto the remote on GitHub - Create an
alphabranch for initial pre-releases before promoting to stablev1.0.0 - Push the
alphabranch to the remote on GitHub - Create a new granular access token (as short-lived and narrow-scoped as possible)
- Add that token to local user config (
~/.npmrc) - Run
npx semantic-release --no-cilocally - Visit npmjs.com for the new package
- Configure trusted publishing in settings
- Revoke the token
- Continue pushing commits to
alphauntil ready forv1.0.0, confirming semantic-release works in CI - Merge
alphatomainto promote to stable
Additional touchpoints
- The "Running semantic-release" page (from #6) should mention
--no-cibriefly with a link to the relevant recipe section - The pre-releases recipe is also an opportunity to more explicitly recommend using a pre-release branch (like
alpha) to validate the pipeline before promoting to stable
Open questions
- Should the trusted-publishing guidance be identical across all three recipe files, or tailored to each workflow? (The pre-releases recipe is the most natural fit for the full workflow since it already covers
alpha/betabranches.) - Should we use a Starlight admonition/callout component to visually distinguish this as a platform-specific consideration?
- Should we also cover other registries (GitHub Packages, etc.) or keep it npm-focused for now?
- Is the
alphapre-release branch approach something we want to recommend as a general best practice for all new packages, or present as one option among several? - Any extra thoughts?
Contributor guide
No contributing guide indexed for this repository
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 three release-workflow recipes' "Initial release" sections and the "Running semantic-release" page mentioned in the issue. Document the npm trusted-publishing bootstrap, including the local --no-ci publish and token lifecycle, and connect the pages consistently. Done means the relevant recipes explain the first publish and the running guide links to that guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100