Split-job release workflow + --mode assertion flag#91
Merged
Conversation
Add a `--mode <version-pr|publish>` flag to `bumpy ci release` so each job in a split-job release workflow can assert its expected runtime state and fail loudly on drift instead of silently routing. Updates the project's own release.yaml to use the recommended pattern: a `plan` job (no write perms) gates a `version-pr` job (PR-only creds) and a `publish` job (scoped to a new `publish` GitHub Environment with id-token: write), so npm trusted-publisher OIDC can be pinned to the environment and NPM_TOKEN exposure can be scoped via env secrets. Internal: ReleaseOptions field `mode: 'auto-publish' | 'version-pr'` renamed to `autoPublish: boolean` for clarity; new `assertMode` field carries the assertion. `--mode` + `--auto-publish` together is rejected at the CLI level. Docs: github-actions.md restructured to lead with the split-job workflow + environment setup, with the single-job version kept as a simplified alternative. Auto-publish flagged as not recommended.
|
The changes in this PR will be included in the next version bump.
|
The flag asserts the detected mode rather than setting it, so the name should reflect that. Reads more naturally in YAML where there's no surrounding context. Internal `assertMode` field name unchanged.
The prior copy implied --auto-publish defeats a security boundary by combining PR-write and publish credentials. That's misleading — a single-job non-auto-publish workflow has the same credential surface, just split across two runs. The actual cost of --auto-publish is purely the loss of the Version Packages PR preview/review gate. Tightens the wording in cli.md/github-actions.md, drops the README mention, shrinks the github-actions.md section to a brief pointer, and adds a docstring on autoPublish() so future readers don't re-derive the wrong conclusion.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
--expect-mode <version-pr|publish>tobumpy ci releasefor asserting the detected release mode (errors instead of silently smart-routing when the runtime state doesn't match what the job expects). Cannot be combined with--auto-publish.planjob gating aversion-prjob (PR-write creds only) and apublishjob (environment: publish,id-token: writefor npm trusted publishing).Why
Without a split, every push to main runs a job with
id-token: write(orNPM_TOKENin env) — even when the workflow is only updating the Version Packages PR. The split scopes those credentials to the publish job only and lets the npm trusted publisher be pinned to a specific GitHub Environment so rogue workflow files in the repo can't request a valid OIDC token.The
--expect-modeflag turns the split's implicitif:gate into an explicit runtime assertion: if the publish job somehow runs while bump files are still present (a race, weird merge, or someone manually re-triggers it), it fails fast instead of silently falling into the version-pr code path.Setup required after merge
publishon each package's npmjs.com settings → Trusted Publishers → GitHub Actions. (Already done.)publishenvironment manually in repo Settings → Environments and restrict deployment branches tomainonly. This is cheap defense in depth — auto-create works too if you skip this. (Already done.)The new docs framing makes the split clearer:
BUMPY_GH_TOKEN. That's it.npmStaged: true).Notable internals
ReleaseOptions.mode: 'auto-publish' | 'version-pr'renamed toautoPublish: boolean— cleaner CLI-flag-to-internal mapping. NewassertMode?: 'version-pr' | 'publish'field carries the assertion. The only caller is packages/bumpy/src/cli.ts.ciReleaseCommandnow computesdetectedModeonce and consolidates the two near-identical "fall through to publish" branches.--expect-mode(reads natural in YAML); the internal field staysassertMode(technically accurate at the code level).Test plan
bun run check— typecheck + format cleanbun run test— 225 tests passplan→version-prpath here, since this PR itself ships with a bump file)🤖 Generated with Claude Code