From 193208f917df48b6c28323e4bde579f8c66cc136 Mon Sep 17 00:00:00 2001 From: Theo Ephraim Date: Fri, 12 Jun 2026 15:15:10 -0700 Subject: [PATCH] docs: note environment deployment-branch restrictions must allow channel branches --- docs/github-actions.md | 2 +- docs/prereleases.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/github-actions.md b/docs/github-actions.md index dca9cef..b952b14 100644 --- a/docs/github-actions.md +++ b/docs/github-actions.md @@ -211,7 +211,7 @@ That's it — the `publish` environment auto-creates on the first publish run, s If you create the environment manually in repo Settings → Environments _before_ the first publish, you can attach protection rules: -- **Restrict deployment branches to `main`** — recommended. Cheap defense in depth: non-`main` refs can never request an OIDC token from this environment, even if a workflow trigger is accidentally widened later. +- **Restrict deployment branches to `main`** — recommended. Cheap defense in depth: non-`main` refs can never request an OIDC token from this environment, even if a workflow trigger is accidentally widened later. If you use [prerelease channels](prereleases.md), also add each channel branch (e.g. `next`) to the allowed list — otherwise channel publishes fail when the job can't enter the environment. - **Required reviewers** — optional. Adds a manual approval gate before each publish. Usually redundant if `npmStaged: true` is enabled (below), since you already have a 2FA approval gate on npmjs.com. **Recommended publish config** — enable provenance and staged publishing for maximum security: diff --git a/docs/prereleases.md b/docs/prereleases.md index ad87816..c17ac41 100644 --- a/docs/prereleases.md +++ b/docs/prereleases.md @@ -137,6 +137,8 @@ on: That's the only workflow change. `bumpy ci release` reads the current branch, looks up the channel in `_config.json`, and behaves accordingly. +> **If your publish job runs in a GitHub Environment with deployment branch restrictions** (the [recommended hardening](github-actions.md#optional-hardening-protection-rules-on-the-publish-environment) restricts it to `main`), add each channel branch to the environment's allowed deployment branches (repo Settings → Environments → publish → Deployment branches). Otherwise the publish job can't run from the channel branch — with npm trusted publishing this means OIDC token requests are rejected and channel publishes fail. + > Make sure the checkout step uses `fetch-depth: 0` (the [release workflow](github-actions.md) already requires this) — the channel publish trigger diffs the triggering push to detect release PR merges. > The PR check workflow (`bumpy-check.yaml`) needs no changes — it runs on `pull_request_target` and handles any base branch.