From 9a48d92de1dc5f6b25c0d00ebfbf6d7ba91d88f8 Mon Sep 17 00:00:00 2001 From: Hiroshi Ogawa Date: Wed, 1 Jul 2026 15:22:48 +0900 Subject: [PATCH] docs: document release protections in CONTRIBUTING (#10689) Co-authored-by: Hiroshi Ogawa <4232207+hi-ogawa@users.noreply.github.com> Co-authored-by: OpenCode (claude-opus-4-8) --- CONTRIBUTING.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d0febfb4..f65b954c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -178,6 +178,26 @@ Releases — publishing the npm packages, creating the git release tag, and gene 4. **Approve the npm staged publish.** Review the staged packages on npm, then approve them with 2FA so the release becomes installable. Afterwards, confirm npm, the tag, and the GitHub release all look right. +### Release Protections + +A few settings outside this repository guard the release process above: GitHub rulesets that keep release branches and tags from being changed by hand, a `Release` environment that requires a maintainer to approve each publish, and npm settings that decide how packages are published. + +- **Protect releases** — branch ruleset on `main` and the `v*` lines, so release branches only change through reviewed pull requests. + - required pull request with at least one approval, stale approvals dismissed on push; the reviewed PR merge is the single auditable entry point for changes to a release line. + - squash-only merges; keeps release-branch history to one commit per PR, so `chore: release v*` lands as a clean, identifiable trigger commit. + - force-push and branch deletion blocked; release history cannot be silently rewritten or dropped. + - code scanning must pass; workflow-security findings block the merge before they can reach a release branch. +- **Protect tags** — tag ruleset on the `v*` release tags, so a tag always maps to a real publish run. + - manual creation, update, and deletion blocked; nobody can hand-craft or move a release tag. + - only the [`vitest-release-bot`](https://github.com/organizations/vitest-dev/settings/apps/vitest-release-bot) GitHub App may bypass; the publish workflow is the sole way a `v*` tag gets pushed. +- **Release environment** — deployment gate on the [`Publish Package`](./.github/workflows/publish.yml) workflow, so a human approves each publish. + - required reviewer; publishing pauses until a maintainer approves the `Release` environment deployment. + - self-review disabled; the maintainer who triggered the release cannot approve their own publish. + - deployment restricted to `main` and the `v*` branches; a publish can only run from a real release branch, never from an arbitrary or feature branch. +- **npm publishing** — npm settings control how packages are authenticated and released. + - trusted publishing (OIDC); each package's trusted publisher on npm pins the source repository (`vitest-dev/vitest`), workflow file (`publish.yml`), and environment (`Release`), so publishes use short-lived tokens from that workflow alone with no long-lived npm token to leak, and they carry provenance attestation automatically so users can trace a package back to the exact workflow run that produced it. + - staged publishing; a publish run only stages the packages, and they go live only after a maintainer reviews and approves them on npm with 2FA, so a bad or accidental publish can be discarded before it becomes installable. + ### Issue Triaging Workflow ```mermaid -- 2.51.2