Skip to content

ci(publish): name npm-publish as the approval gate for every publish - #7870

Queued
michaelwang11394 wants to merge 4 commits into
mainfrom
ci-prerelease-approval
Queued

michaelwang11394 wants to merge 4 commits into
mainfrom
ci-prerelease-approval

Conversation

@michaelwang11394

@michaelwang11394 michaelwang11394 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

What

The publish job keeps environment: npm-publish for every trigger. A comment, a workflow test and the release docs now state that npm-publish is the approval gate. Every publish, stable or prerelease, waits for a maintainer other than the one who started it to approve the run.

Stacked on #7869.

Why

Prerelease tags are published from next, alpha and prerelease/* branches, and no PR review covers those branches. The environment approval is the only review a prerelease gets, so the workflow must not move the publish job to an ungated environment. The test fails if it does.

A separate npm-prerelease environment was considered and dropped. npm's trusted publishers for every package are pinned to npm-publish, so a job in another environment would fail npm auth.

Related work

Stacked on #7869, which moves the build out of the job that holds the npm token.

How

  • publish.yml: a comment on environment: npm-publish says why every trigger uses it.
  • scripts/publish-workflow.test.mjs: the publish job's environment is npm-publish, and no other job has an environment.
  • docs/contributing/release-channels.mdx: the stable and alpha flows each say the run waits for approval, and the CI guardrails list it.

Test plan

  • Unit tests added/updated
  • Manual testing performed
  • Documentation updated (if applicable)
  • Comments follow CONTRIBUTING.md "Comments": they say why, not what, and a bug fix says what the code must do and how to reproduce the bug

What I measured

  • node --test scripts/publish-workflow.test.mjs: 15 of 15 pass.
  • The repository API shows npm-publish has a required_reviewers rule with three reviewers and prevent_self_review: true.

What I did NOT exercise

  • A real prerelease tag push through the approval.

…e-commit code

Builds, lifecycle scripts and packing move to a pack job with a read-only
token and no secrets. The publish job, which holds the npm token and the
write token, checks each tarball's name and version against the release and
uploads it with lifecycle scripts off. A version already on npm with other
contents fails the first attempt instead of being skipped.
…proves

A prerelease tag can come from any prerelease branch, which no PR review
covers. Tag-push runs now use the npm-prerelease environment, which requires
a maintainer's approval. Merged release PRs keep the npm-publish environment.

@jrusso1020 jrusso1020 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE @ d2457e0. The code change is correct: tag pushes select npm-prerelease, merged release PRs keep npm-publish, and the new test pins both the expression and that publish is the only job with an environment.

Need ✅ · Size ✅ · Reuse ✅ · Simpler ✅ · Structure ✅ · Risk: low (the security value depends on environment setup, below)

The gate is only as strong as the environment configuration. A tag push runs the workflow file from the tagged commit, so whoever can push a prerelease tag can also edit publish.yml on that commit. That edit could drop environment:, name npm-publish instead, or read the npm credential from another job. Besides the admin steps in the description (required reviewers, prevent self-review, v*-* tags, credential added), the approval only holds if both of these are true:

  1. The npm credential exists only as an environment secret on npm-prerelease and npm-publish, with no repository- or organization-level secret of the same or any other name that this repo can read. Otherwise any job in an edited workflow can use it without approval.
  2. npm-publish refuses tag refs. Its deployment-branch policy must not admit refs/tags/*, so an edited workflow on a tag push can't pick the ungated environment.

Worth adding both lines to the setup checklist in the description, and a sentence in release-channels.mdx, so the next person who touches the environments keeps them.

No other findings. Not merging; per the description it waits for the environment to exist.

— Rames

@jrusso1020

Copy link
Copy Markdown
Collaborator

Maintainers decided to keep a single publish environment rather than adding npm-prerelease: the npm trusted publisher for every package is pinned to npm-publish, so a job in another environment would fail OIDC auth. npm-publish now has required reviewers with self-review prevented, so prerelease tag pushes already wait for a maintainer approval (stable releases do too).

Could you drop the environment switch in publish.yml (keep environment: npm-publish for every trigger) and update the docs and the workflow test to name npm-publish as the approval-gated environment?

— Rames

…ironment

npm's trusted publishers are pinned to npm-publish, and that environment now
requires a maintainer's approval with self-review prevented. A second
environment would fail npm auth, so the workflow keeps npm-publish for every
trigger. The docs and test name it as the approval gate.
@michaelwang11394 michaelwang11394 changed the title ci(publish): prerelease tag pushes publish only after a maintainer approves ci(publish): name npm-publish as the approval gate for every publish Nov 15, 2026
@michaelwang11394

Copy link
Copy Markdown
Contributor Author

Done in 7ec7e28. The environment switch is gone, so environment: npm-publish applies to every trigger, with a comment saying why. The test now checks that the publish job uses npm-publish and that no other job has an environment. The docs name npm-publish as the approval step in both the stable and alpha flows.

🤖 Addressed by Claude Code

jrusso1020
jrusso1020 previously approved these changes Nov 15, 2026

@jrusso1020 jrusso1020 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE @ 7ec7e28. One gated environment for every trigger is simpler than the two-environment split, and it closes the concern from my last review.

Need ✅ · Size ✅ (3 files, +16/−8 vs my last review) · Reuse ✅ (same environment main already uses) · Simpler ✅ (drops the second environment) · Structure ✅ · Risk: low

My earlier conditions, rechecked against the repository settings:

  • No ungated environment to fall back to. Every publish now runs in npm-publish, so there's no second environment for a changed workflow to select. npm-publish has the required_reviewers rule (3 reviewers, prevent_self_review: true). None of the repo's other environments holds a secret.
  • Tags are admitted. On main, the v0.9.28-alpha.* tag pushes already published through npm-publish, so its deployment policy accepts prerelease tags. My old ask that npm-publish refuse tags no longer applies with one environment.
  • Credential location. No secret named NPM_TOKEN is visible to this repo at environment, repository or organization level. Publishing therefore authenticates through npm trusted publishing. With npm's trusted publishers pinned to npm-publish as you describe, a job outside that environment can't authenticate. I can't see npm's side from GitHub, so that pin is the one thing I took on trust.

Tests: node --test scripts/publish-workflow.test.mjs passes 15/15 at head. With the publish job's environment changed back to the old two-environment expression, the new test fails (not ok 15), so it pins the gate.

Non-blocking:

  1. NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} now resolves to nothing. Consider dropping it, so that a token added later at repo or org level doesn't quietly become a second way to authenticate. If a token is ever needed, keep it as an environment secret on npm-publish only.
  2. A correction to my #7869 review: id-token: write is needed for trusted publishing. Keep it, and ignore that nit.

— Rames

Base automatically changed from ci-publish-from-packed-tarballs to main November 15, 2026 23:42
@michaelwang11394
michaelwang11394 dismissed jrusso1020’s stale review November 15, 2026 23:42

The base branch was changed.

@mintlify

mintlify Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
hyperframes 🟢 Ready View Preview Nov 15, 2026, 11:47 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

# Conflicts:
#	.github/workflows/publish.yml
#	scripts/publish-workflow.test.mjs

@jrusso1020 jrusso1020 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review at d69e48383bf4a39b00345a200c74c688f454de47, a merge of main after #7869 landed.

Verdict: APPROVE. The diff against main is now the three files I approved at 7ec7e28f, and nothing else (+16/−1):

  • publish.yml only adds the comment above environment: npm-publish.
  • The release-channels.mdx text and the new test are unchanged.
  • publish is still the only job with an environment.

At this head, node --test scripts/publish-workflow.test.mjs passes 15 of 15.

The NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} line is now on main (it came in with #7869), so it's outside this diff. It's still dead under trusted publishing and can go in a follow-up.

Need: yes · Size: ok (3 files, +16/−1) · Reuse: unchanged · Simpler: already minimal · Structure: fine
Risk: low — one environment line and docs; the approval gate's settings are unchanged

— Rames

@michaelwang11394
michaelwang11394 added this pull request to the merge queue Nov 16, 2026
Any commits made after this event will not be merged.

This branch was successfully deployed

1 active deployment
staging - docs — d69e4838 Deployed Nov 15, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants