On this page
Release lifecycle: run, resume, scaffold release files, retry CI, sync notes, undo, deprecate, yank, scrub history, and reconcile tags after a rewrite.
#rlsbl release
Release orchestration commands covering the full release lifecycle. Provides 10 subcommands: run, resume, init, retry, edit, undo, deprecate, yank, scrub, reconcile.
#release run
Bump version, validate the JSONL changelog, run tests and lint, commit, tag, push, and create a GitHub Release. Reads the bump type (patch, minor, major, or infra) and target selection from .rlsbl/releases/unreleased.toml, which can be scaffolded with rlsbl release init. Supports dry-run preview, --approve-consequential to skip the confirmation prompt in non-interactive contexts, and --allow-dirty to skip the clean working tree check.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--push-timeout | int | Timeout in seconds for each git push. Overrides the push_timeout config key; 0 (the default) means use push_timeout, else the shipped default. | |||
--ci-timeout | int | Timeout in seconds for the release CI gate (the wait for CI to conclude on the pushed release candidate). Overrides the ci_timeout config key; 0 (the default) means use ci_timeout, else the shipped default. | |||
--check-timeout | int | Timeout in seconds for each preflight check subprocess (tests, lint, external checks). Overrides the check_timeout config key; 0 (the default) means use check_timeout, else the shipped default. | |||
--hook-timeout | int | Timeout in seconds for each release hook. Overrides the hook_timeout config key; 0 (the default) means use hook_timeout, else no timeout. | |||
--watch | bool | After release, automatically watch CI runs to completion (--no-watch to skip) | |||
--allow-dirty | bool | Skip the clean working tree check and allow releasing with uncommitted changes | |||
--bump | str | Bump type: patch, minor, major, infra, prerelease. Skips the release file. | |||
--description | str | Short release description summarizing the changes (required with --bump) | |||
--preid | str | Pre-release identifier: alpha, beta, rc, stable. Only valid with --bump. |
#release resume
Resume a previously failed release from where it left off. Reads the in-progress state file (.rlsbl/releases/in-progress.json, or .rlsbl-monorepo/releasables/
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--push-timeout | int | Timeout in seconds for each git push. Overrides the push_timeout config key; 0 (the default) means use push_timeout, else the shipped default. | |||
--ci-timeout | int | Timeout in seconds for the release CI gate (the wait for CI to conclude on the pushed release candidate). Overrides the ci_timeout config key; 0 (the default) means use ci_timeout, else the shipped default. | |||
--check-timeout | int | Timeout in seconds for each preflight check subprocess (tests, lint, external checks). Overrides the check_timeout config key; 0 (the default) means use check_timeout, else the shipped default. | |||
--hook-timeout | int | Timeout in seconds for each release hook. Overrides the hook_timeout config key; 0 (the default) means use hook_timeout, else no timeout. | |||
--watch | bool | After release, automatically watch CI runs to completion (--no-watch to skip) |
#release init
Scaffold a .rlsbl/releases/unreleased.toml file by auto-detecting project targets. The generated file contains a default bump type (patch), an include list of all detected targets, and per-target configuration sections for Flutter targets.
Effect: mutating
Dry run: not supported — the command scaffolds a file whose point is that you edit it before releasing; printing that file instead of writing it leaves nothing to edit
#release retry
Dispatch CI/CD workflows for a completed release via gh workflow run. Reads the dispatch list and ref from .rlsbl/releases/retry.toml, which is auto-scaffolded with sensible defaults if missing. Verifies the GitHub Release exists before dispatching. Each workflow in the dispatch list is triggered against the configured ref (defaults to the release tag).
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--watch | bool | After retry, automatically watch CI runs to completion (--no-watch to skip) |
#release edit
Sync the GitHub Release notes for a given version with the corresponding CHANGELOG.md entry. Defaults to the current version if none is specified. Use --dry-run to preview changes without updating GitHub.
Effect: mutating
#Arguments
| Name | Required | Description |
|---|---|---|
version | no | Version whose GitHub Release notes to sync (defaults to current version) |
#release undo
Revert a release. Without --version, reverts the latest release (deletes GitHub Release, removes git tag, reverts version bump commit). With --version, reverts a non-latest release if it is provably unpublished (probes registries for evidence, deletes GitHub Release + tag only, un-finalizes changelog).
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--target | str | Target a specific registry for version detection (auto-detected if omitted) | |||
--version | str | Version to undo (for non-latest releases that are provably unpublished) |
#release deprecate
Mark a past release as deprecated. Sets the GitHub Release pre-release flag and prepends a deprecation notice to the release notes. Use --reason to explain why and --use to suggest a replacement version.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--reason | str | Human-readable explanation of why this version is being deprecated | |||
--use | str | Suggest this version as a replacement in the deprecation notice |
#Arguments
| Name | Required | Description |
|---|---|---|
version | yes | Semver string of the release to deprecate, with or without v prefix (e.g. 0.9.1) |
#release yank
Remove a published version from package registries. Probes each configured target's registry to determine publication status, then executes registry-specific removal: npm deprecate, Go retract, or PyPI manual checklist. Also marks the GitHub Release as pre-release with a yank notice.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--reason | str | Human-readable explanation of why this version is being yanked | |||
--use | str | Suggest this version as a replacement in the yank notice |
#Arguments
| Name | Required | Description |
|---|---|---|
version | yes | Semver string of the release to yank, with or without v prefix (e.g. 0.9.1) |
#release scrub
Scrub sensitive content from git history and update release metadata to match the rewritten commits. Supports 3 modes: match (--pattern), file (--file), or recipe (--recipe). After rewriting, remaps commit hashes in JSONL changelog files, regenerates CHANGELOG.md, force-pushes, and recreates GitHub Releases on the new tags.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--replace | str | Match mode: literal text to substitute for each match (mutually exclusive with --mangle) | |||
--mangle | bool | Match mode: replace matched content with random ASCII of same length (mutually exclusive with --replace) | |||
--reason | str | Reason for scrubbing (required, used in commit message) | |||
--pattern | str | Match mode: regex pattern to match against file contents (mutually exclusive with --file and --recipe) | |||
--file | str | File mode: path of the file to rewrite throughout history; it is replaced with its current on-disk content, or removed if absent (mutually exclusive with --pattern and --recipe; requires --from-commit) | |||
--recipe | str | Recipe mode: path to a scrub recipe TOML file executed via safegit scrub run; per-operation pattern/replace/mangle live inside the recipe (mutually exclusive with --pattern and --file) | |||
--from-commit | str | SHA of the earliest commit to rewrite (all descendants are also rewritten) | |||
--entire-history | bool | Rewrite every commit in the repository from the initial commit onward (match and recipe modes only; file mode requires --from-commit) |
#release reconcile
Reconcile release metadata with a rewritten history: re-push the tags a rewrite moved and recreate the GitHub Releases attached to them. Reads safegit's rewrite journal (.git/safegit/rewrite-maps.jsonl) to determine what moved, so it works after ANY out-of-band rewrite, not just one driven by rlsbl release scrub. Fail-closed: a tag whose divergence from the remote the journal does not explain is a hard error, never a force-push.
Effect: mutating · consequential (prompts before running; --approve-consequential skips)
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--push-timeout | int | Timeout in seconds for each tag push. Overrides the push_timeout config key; 0 (the default) means use push_timeout, else the shipped default. |