From 54eb11c9e08c33151ce2e017199ef1972e1cbd6c Mon Sep 17 00:00:00 2001 From: Theo Ephraim Date: Fri, 12 Jun 2026 19:12:47 -0700 Subject: [PATCH 1/3] docs: channel branches in release workflow + promotion-PR check behavior - Release workflow examples: comment that channel branches go in the push trigger too, and switch the concurrency group to per-ref so a channel publish doesn't queue behind / get cancelled by a main release (the lesson from dogfooding the next channel). - Concurrency section: explain the per-ref group and when it matters. - prereleases.md setup: note existing single-group workflows need the per-ref change. - cli.md: document what 'ci check' shows on channel and promotion PRs. --- docs/cli.md | 2 ++ docs/github-actions.md | 20 +++++++++++++++++--- docs/prereleases.md | 4 +++- 3 files changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 51400a0..7a6045d 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -190,6 +190,8 @@ bumpy ci check --no-fail Requires `GH_TOKEN` environment variable (automatically available in GitHub Actions). +**On channel and promotion PRs:** for a PR targeting a [prerelease channel](prereleases.md) branch, the comment is channel-aware — it shows the prerelease plan (`-.x` versions) and the target dist-tag rather than implying a stable release. For a **promotion PR** (a channel branch → `main`, or a graduation like `alpha` → `beta`), the check reads the cycle's already-shipped bump files from `.bumpy//` and shows the consolidated stable plan, calling out that merging ends the prerelease cycle. (Feature PRs that _target_ a channel branch are checked against that branch, so only the PR's own new bump files count — see [`--base`](#bumpy-check) on the local `check` command for the equivalent locally.) + ## `bumpy ci plan` CI command that reports what `ci release` would do, without acting. Outputs JSON to stdout and sets GitHub Actions step outputs so you can conditionally run expensive steps (builds, etc.) only when needed. diff --git a/docs/github-actions.md b/docs/github-actions.md index b952b14..f04d5b4 100644 --- a/docs/github-actions.md +++ b/docs/github-actions.md @@ -108,10 +108,15 @@ The recommended release workflow splits version-PR maintenance from publishing i name: Bumpy Release on: push: + # Add any prerelease channel branches here too, e.g. [main, next, beta]. + # See the prerelease channels docs: https://github.com/dmno-dev/bumpy/blob/main/docs/prereleases.md branches: [main] concurrency: - group: bumpy-release + # Per-branch so a channel (e.g. next) publish doesn't queue behind — or get + # cancelled by — a main release. Drop the `-${{ github.ref }}` if you never + # add channel branches above. + group: bumpy-release-${{ github.ref }} cancel-in-progress: false jobs: @@ -257,10 +262,15 @@ For simpler setups, you can run everything in a single job. `bumpy ci release` w name: Bumpy Release on: push: + # Add any prerelease channel branches here too, e.g. [main, next, beta]. + # See the prerelease channels docs: https://github.com/dmno-dev/bumpy/blob/main/docs/prereleases.md branches: [main] concurrency: - group: bumpy-release + # Per-branch so a channel (e.g. next) publish doesn't queue behind — or get + # cancelled by — a main release. Drop the `-${{ github.ref }}` if you never + # add channel branches above. + group: bumpy-release-${{ github.ref }} cancel-in-progress: false jobs: @@ -321,12 +331,16 @@ Use a concurrency group on your release workflow to prevent overlapping publish ```yaml concurrency: - group: bumpy-release + # Per-ref: serialize runs within a branch, but let different branches run in + # parallel. Drop the `-${{ github.ref }}` if you only ever release from main. + group: bumpy-release-${{ github.ref }} cancel-in-progress: false # queue rather than cancel — don't skip releases ``` This is included in all the workflow examples above. +The `-${{ github.ref }}` matters once you add [prerelease channels](prereleases.md): a single shared group (`bumpy-release`) would make a `next` prerelease publish queue behind — or, with `cancel-in-progress: true`, get cancelled by — a `main` release, even though they touch different dist-tags and never conflict. Per-ref keeps each branch's releases serialized against themselves while letting `main` and `next` proceed independently. If you release only from `main`, the plain `bumpy-release` group is equivalent. + ## Token setup ### `GH_TOKEN` (required) diff --git a/docs/prereleases.md b/docs/prereleases.md index 32bd6a8..cfcf73a 100644 --- a/docs/prereleases.md +++ b/docs/prereleases.md @@ -135,7 +135,9 @@ on: branches: [main, next] # add channel branches here ``` -That's the only workflow change. `bumpy ci release` reads the current branch, looks up the channel in `_config.json`, and behaves accordingly. +That's the only trigger change. `bumpy ci release` reads the current branch, looks up the channel in `_config.json`, and behaves accordingly. + +> **Concurrency:** if your workflow uses a single `concurrency.group` (e.g. `bumpy-release`), make it per-ref (`bumpy-release-${{ github.ref }}`) so a channel publish doesn't queue behind — or get cancelled by — a `main` release. The [recommended release workflow](github-actions.md#release-workflow-recommended-split-jobs) already does this. > **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. From 303619b3f7251c8cf823a6bbf7ace95a4fdd56df Mon Sep 17 00:00:00 2001 From: Theo Ephraim Date: Fri, 12 Jun 2026 19:15:47 -0700 Subject: [PATCH 2/3] docs: make per-ref concurrency the unconditional default (no opt-out comment) --- docs/github-actions.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/docs/github-actions.md b/docs/github-actions.md index f04d5b4..57765a1 100644 --- a/docs/github-actions.md +++ b/docs/github-actions.md @@ -113,9 +113,7 @@ on: branches: [main] concurrency: - # Per-branch so a channel (e.g. next) publish doesn't queue behind — or get - # cancelled by — a main release. Drop the `-${{ github.ref }}` if you never - # add channel branches above. + # Per-ref: serialize a branch's releases, let different branches run in parallel group: bumpy-release-${{ github.ref }} cancel-in-progress: false @@ -267,9 +265,7 @@ on: branches: [main] concurrency: - # Per-branch so a channel (e.g. next) publish doesn't queue behind — or get - # cancelled by — a main release. Drop the `-${{ github.ref }}` if you never - # add channel branches above. + # Per-ref: serialize a branch's releases, let different branches run in parallel group: bumpy-release-${{ github.ref }} cancel-in-progress: false @@ -331,15 +327,11 @@ Use a concurrency group on your release workflow to prevent overlapping publish ```yaml concurrency: - # Per-ref: serialize runs within a branch, but let different branches run in - # parallel. Drop the `-${{ github.ref }}` if you only ever release from main. group: bumpy-release-${{ github.ref }} cancel-in-progress: false # queue rather than cancel — don't skip releases ``` -This is included in all the workflow examples above. - -The `-${{ github.ref }}` matters once you add [prerelease channels](prereleases.md): a single shared group (`bumpy-release`) would make a `next` prerelease publish queue behind — or, with `cancel-in-progress: true`, get cancelled by — a `main` release, even though they touch different dist-tags and never conflict. Per-ref keeps each branch's releases serialized against themselves while letting `main` and `next` proceed independently. If you release only from `main`, the plain `bumpy-release` group is equivalent. +This is included in all the workflow examples above. Per-ref serializes each branch's releases against themselves while letting different branches publish in parallel. It's the right default everywhere: with a single release branch it behaves identically to a plain group, and once you add [prerelease channels](prereleases.md) it stops a `next` prerelease publish from queueing behind — or, with `cancel-in-progress: true`, being cancelled by — a `main` release, even though they touch different dist-tags and never conflict. ## Token setup From ed88640900c5e0aa433910dc8286ea68b07e66ac Mon Sep 17 00:00:00 2001 From: Theo Ephraim Date: Fri, 12 Jun 2026 19:17:08 -0700 Subject: [PATCH 3/3] docs: drop concurrency migration note (few existing users, recommended example already covers it) --- docs/prereleases.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/prereleases.md b/docs/prereleases.md index cfcf73a..32bd6a8 100644 --- a/docs/prereleases.md +++ b/docs/prereleases.md @@ -135,9 +135,7 @@ on: branches: [main, next] # add channel branches here ``` -That's the only trigger change. `bumpy ci release` reads the current branch, looks up the channel in `_config.json`, and behaves accordingly. - -> **Concurrency:** if your workflow uses a single `concurrency.group` (e.g. `bumpy-release`), make it per-ref (`bumpy-release-${{ github.ref }}`) so a channel publish doesn't queue behind — or get cancelled by — a `main` release. The [recommended release workflow](github-actions.md#release-workflow-recommended-split-jobs) already does this. +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.