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

A member of the Team first needs to authorize it.

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

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.

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?

this is a great question. i dont necessarily want to promise that the versions in at least this part of the docs suggest compatible versions, but i worry that not using real version numbers could confuse folks further. for now, i think it is ok to leave as is

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?

i think this concern is valid whether or not plugins are included in the npx command. however, these changes are in code in the repository. if an update is merged that breaks the configuration, the previous combination is still in history, so the update can be reverted to get back to a working setup. that is a far better situation to be in than not knowing the versions that were in place before becoming broken. i think i'll merge the current iteration because it is already better than the current state, but if you'd like to suggest an improvement for this as a follow up, we'd welcome it

for another potential follow-up, it could be useful to apply the same guidance in the example here, too: https://semantic-release.org/foundation/plugins/#additional-plugins