semantic-release / semantic-release/docs

Add recipe for publishing your first npm package with trusted publishing

Open
#7 1 comment 0 reactions 0 assignees View on GitHub

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-ci locally 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)
  1. Scaffold out a new package repo
  2. Push main to the remote on GitHub
  3. Create an alpha branch for initial pre-releases before promoting to stable v1.0.0
  4. Push the alpha branch to the remote on GitHub
  5. Create a new granular access token (as short-lived and narrow-scoped as possible)
  6. Add that token to local user config (~/.npmrc)
  7. Run npx semantic-release --no-ci locally
  8. Visit npmjs.com for the new package
  9. Configure trusted publishing in settings
  10. Revoke the token
  11. Continue pushing commits to alpha until ready for v1.0.0, confirming semantic-release works in CI
  12. Merge alpha to main to promote to stable
Additional touchpoints
  • The "Running semantic-release" page (from #6) should mention --no-ci briefly 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
  1. 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/beta branches.)
  2. Should we use a Starlight admonition/callout component to visually distinguish this as a platform-specific consideration?
  3. Should we also cover other registries (GitHub Packages, etc.) or keep it npm-focused for now?
  4. Is the alpha pre-release branch approach something we want to recommend as a general best practice for all new packages, or present as one option among several?
  5. Any extra thoughts?

Contributor guide

No contributing guide indexed for this repository

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.