docs: recommend pinning plugins and presets in npx command

[igordanchenko]

Summary

Extends the version pinning guidance on the Running semantic-release page to cover plugins and presets, not just semantic-release itself.

Follow-up to the discussion in conventional-changelog/conventional-changelog#1495.

Open Questions

@travi

1. How would you prefer to handle version drift in the pinned examples? Add a note saying the versions are current as of July 2026? Or use generic @^X / @^Y placeholders?

2. A related question about the Renovate guidance: an automated Renovate config can cause the very same issue version pinning is trying to avoid — a major bump of a pinned preset (e.g. conventional-changelog-conventionalcommits@9 → @10) passes CI and silently ships empty release notes. Should the Renovate example stay semantic-release-only, or also cover plugin pins?

[vercel]

@igordanchenko is attempting to deploy a commit to the Semantic Release Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
semantic-release-docs	Ready	Preview, Comment	Jul 6, 2026 6:47pm

[igordanchenko]

While adopting this exact recommendation in one of my projects, I ran into a footgun that may be worth a note in the docs.

npx exports its --package specs to child processes as the npm_config_package environment variable, so every process semantic-release spawns inherits them — including git hooks invoked by git push. If the repository uses a git hook that runs npx in no-install mode (e.g., the fairly common husky pre-push hook npx --no -- commitlint ...), the inner npx picks up the leaked specs and fails the release at the git push --tags step:

npm error npx canceled due to missing packages and no YES option: ["semantic-release@25.0.5","conventional-changelog-conventionalcommits@9.3.1"]
husky - pre-push script failed (code 1)

The catch is that this only happens with pinned specs — i.e., exactly when following this PR's recommendation. A bare package name parses as the * range and is treated as satisfied by whatever is already in the project's node_modules or the npx cache. For version-ranged specs (@25, @9), however, libnpmexec always re-resolves against the registry and schedules an install (its cache check deliberately rejects ranges: "the npx tree shouldn't be ok w/ an outdated version"), which the hook's --no turns into a hard failure. So a workflow that ran fine unpinned starts failing the moment the pins are added — failing run for reference.

Adding --yes to the outer command doesn't help: the hook's explicit --no CLI flag takes precedence over the inherited npm_config_yes. What does work is disabling git hooks in the release job — reasonable there anyway, since hooks guard local development and CI has already validated the commits:

- name: Release
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    HUSKY: 0
  run: npx --package semantic-release@25 --package conventional-changelog-conventionalcommits@9 semantic-release

(Verified fix — the same workflow released successfully with HUSKY: 0.)

Happy to fold a short warning about this into the PR if you think it belongs on this page.