GitHub guides · Platform setup · CLI reference
Destination: your application repository → Settings → Secrets and variables → Actions → New repository secret. Select your own dedicated automation key, not a personal key. Run one command at a time; replace YOUR_GPG_KEY_ID with its full fingerprint (preferred) or long key ID after listing, and replace the SSH filename before reading it:
gpg --list-secret-keys --keyid-format=long
# Actions secret BOT_GPG_SECRETKEY: paste the complete private-key block printed next.
gpg --export-secret-key -a YOUR_GPG_KEY_ID
# Actions secret BOT_SSH_SECRETKEY: paste the complete SSH private key printed next.
cat "$HOME/.ssh/YOUR_AUTOMATION_SSH_KEY"Paste each complete BEGIN/END block into its named secret from a private, unrecorded local terminal. Do not save an extra export file or expose output in chat/logs/source. Keep existing public-key registration/write access if already correct; register public keys only if needed. Missing a key? Follow the optional creation steps, then return to this block. These workflows have no GPG/SSH passphrase configured; protected keys need an approved adaptation.
Entering an existing project? Configure the workflow, preserve its version/history, and resume at the applicable release checkpoint below. Do not repeat fresh-repository bootstrap.
Follow this journey in a new greeting-demo repository under your own GitHub account or organization. Stop at each editing, GitHub, and CI checkpoint; this is not a paste-all script.
- Local layout:
$HOME/projects/git-toolsholds the retained tool checkout;$HOME/projects/greeting-demoholds your application. If you choose another parent, use that location consistently. - Example application: a tiny Python module without a package manifest, so
.cz.tomlis its only version file. In a packaged application, reconcile managed manifest/lockfile versions without discarding unrelated changes. - Expected results: exact subjects, serialized merges, default
semver2, and bare-version tags (0.2.0-rc.0, notv0.2.0-rc.0). Extra version-producing pushes change the timeline. Results are derived from the engine/local tests, not a live GitHub deployment.
All human changes after the one-time repository seed go through hosted PRs, including release/hotfix stabilization and synchronization. Protect master, develop, release/*, and hotfix/*; narrowly authorize the version bot's signed pushes. New protected release/hotfix refs may need an approved branch-creation process: creating a ref at an already-reviewed commit is not permission to push new human commits. Use Squash and merge for the serialized example's PRs. If master advances before promotion, the current-master synchronization inner PR must instead use Create a merge commit, with the stated Conventional Commit subject, to preserve master's ancestry. Repository and source-branch rules must allow this narrow exception; never use rebase, an empty inner PR, or a direct human bypass. Develop/backmerge preparation still uses its separate squash-safe recipe.
Install Git, Python 3.12, uv, and GnuPG. Authenticate your local Git/SSH connection to GitHub. From outside any existing repository:
mkdir -p "$HOME/projects"
cd "$HOME/projects"
# Replace the source placeholder with the upstream git-tools clone URL, not your application origin.
git clone YOUR_GIT_TOOLS_SOURCE_URL git-tools
cd git-tools
./scripts/install.shAlready have the tool checkout? Go to it and rerun ./scripts/install.sh instead of cloning again. Keep the checkout: installation is editable. The upstream URL above is the tool source, not your application origin.
Restart your shell, then run git-tools --help. If it is not on PATH, run uv tool update-shell and restart again; see installation for completion setup.
In your own GitHub account or organization, create an empty greeting-demo repository: no generated README, license, or .gitignore. The next section creates its local checkout and configures Actions before the first push.
Optional generated prose: the fixed git commit -m commands and CI need no LLM. If you use git-tools commit or git-tools pr, configure a provider/model with git-tools settings before the first use; prefer its masked credential prompt. See configuration.
Working rule: keep one version adapter, full history, and current tags. After each version-producing push/merge, wait for publication, pull the bot commit, and fetch tags. A follow-up bot run may skip. On failure, stop and use recovery, not force-push or another bootstrap.
Return explicitly to your chosen parent after the shell restart. Replace YOUR_NAME / YOUR_EMAIL with your human Git identity, and YOUR_USERNAME_OR_ORG with the owner of your new GitHub repository. Keep the SSH user git@ unchanged:
cd "$HOME/projects"
mkdir greeting-demo
cd greeting-demo
git init -b master
git config user.name 'YOUR_NAME'
git config user.email 'YOUR_EMAIL'
git remote add origin git@github.com:YOUR_USERNAME_OR_ORG/greeting-demo.git
git-tools init --version 0.0.1 --tag-format '$version'
mkdir -p .github/workflows
cp "$HOME/projects/git-tools/.github/workflows/version-bump-git-flow-variant-release-led.yml.example" .github/workflows/version-bump-git-flow-variant-release-led.ymlBefore the first push, complete GitHub setup:
- In the copied YAML
env:, setGIT_BOT_NAME/GIT_BOT_EMAILto your dedicated automation identity, not your human identity. Keep the upstreamGIT_TOOLS_REPO; choose a supported engine branch/tag inGIT_TOOLS_REF(not a bare SHA). Local installation does not change CI's engine clone. - Follow key setup: use an existing dedicated automation GPG key or create one first, print its private block and paste it into Actions secret
BOT_GPG_SECRETKEY, and read the dedicated SSH private key intoBOT_SSH_SECRETKEYusing the copy block above. Register matching public keys separately only if not already configured. Do not save a private-key export file. - Use PR-title squash messages, disable rebase, and add separate read-only PR tests. Enable Allow merge commits and permit merge commits on
release/*andhotfix/*for reviewed current-master synchronization; do not enforce linear history on those targets. Customize those merge subjects as shown below. Grant the SSH identity write access and narrow bot protection exceptions;GITHUB_TOKENpermission alone is insufficient. Plan the one-time seed exception before final protections.
Create README.md containing # Greeting demo and .gitignore containing __pycache__/. Confirm .cz.toml is 0.0.1, not 0.1.0; any managed package version must match. Do not create a bootstrap tag manually.
git add README.md .gitignore .cz.toml .github/workflows
git diff --cached
git commit -m "Release 0.1.0"
git push -u origin masterTransition: local seed → remote master, subject Release 0.1.0; no PR for this explicitly authorized fresh-repository seed. Set GitHub's default branch to master once it exists. Wait for Actions: it must commit stable 0.1.0 and publish tag 0.1.0. Then bring that bot commit and tags home:
git switch master
git pull --ff-only origin master
git fetch origin --tags
git show HEAD:.cz.toml
git tag --list '0.1.0'
git switch -c develop
git push -u origin developTransition: master → new develop, no PR/title and no new content. Wait for its workflow; the generated bump subject should skip. Both branches remain 0.1.0, with no new tag. Enable the planned steady-state protections now, retaining only the bot exception and approved ref-creation procedure.
For every subsequent local branch start, pull with --ff-only and fetch tags as shown. A failed fast-forward is a stop-and-inspect signal, not a reason to reset away work. Do not edit version fields on ordinary feature branches or run local mutating bumps alongside CI.
git switch develop
git pull --ff-only origin develop
git fetch origin --tags
git switch -c feature/greetingCreate greeting.py with this actual implementation:
def greet(name):
return f"Hello, {name}!"Create tests/test_greeting.py (create tests/ first):
import unittest
from greeting import greet
class GreetingTests(unittest.TestCase):
def test_named_greeting(self):
self.assertEqual(greet("Ada"), "Hello, Ada!")python -m unittest discover -s tests
git add greeting.py tests/test_greeting.py
git diff --cached
git commit -m "feat: add named greeting"
git push -u origin feature/greetingWait for the feature-branch workflow: version stays 0.1.0, no tag (feature branches skip publication). Refresh refs before generating PR text:
git fetch origin --tags
git-tools pr --base developIn GitHub, create feature/greeting → develop, title feat: add named greeting. Request review, wait for PR checks, then squash-merge with that final subject. This deliberately uses an ordinary feat: from stable 0.1.0: normal minor detection opens 0.2.0-alpha.0. Release-led does not require a Start title for this first feature.
The CLI only generates text: it neither creates nor merges the hosted PR. Inspect/paste its body and enforce the exact title/final subject in GitHub. Wait for develop's post-merge Actions run: expect 0.2.0-alpha.0, tag 0.2.0-alpha.0.
git switch develop
git pull --ff-only origin develop
git fetch origin --tagsYou may use git-tools commit instead of the deterministic git commit -m examples, but it creates a commit by default. For a preview use git-tools commit --no-commit; inspect the result and preserve the stated Conventional Commit subject and hosted PR title if reproducing this version timeline.
git switch -c bugfix/trim-nameEdit greet to return f"Hello, {name.strip()}!". Add a test asserting that greet(" Ada ") equals "Hello, Ada!"; retain the original test. Then:
python -m unittest discover -s tests
git add greeting.py tests/test_greeting.py
git diff --cached
git commit -m "fix: trim greeting names"
git push -u origin bugfix/trim-name
git fetch origin --tags
git-tools pr --base developWait for the source workflow: still 0.2.0-alpha.0, no tag. In GitHub create bugfix/trim-name → develop, title fix: trim greeting names. Review, pass checks, squash-merge with that subject, then wait for develop CI: 0.2.0-alpha.1, tag 0.2.0-alpha.1.
git switch develop
git pull --ff-only origin develop
git fetch origin --tagsgit switch -c release/0.2.0
git push -u origin release/0.2.0Transition: develop at 0.2.0-alpha.1 → new release/0.2.0; no PR/title and no new human commit. Wait for the workflow: it should skip (there is no unique human stabilization commit), leaving 0.2.0-alpha.1, no new tag. Merely naming/creating the branch does not open RC.
The release-led adapter validates release/0.2.0 against stable master 0.1.0: this is a valid minor step. It could select another valid next release line, but this example deliberately retains 0.2.0 to match the feature's normal alpha line. Optional example choice, not a release-led requirement: we use Start 0.3.0 below to select a separate next-cycle develop line explicitly. Unlike classic, release-led does not require this Start PR after the cut: ordinary Conventional Commit PRs can continue develop's existing alpha line while release/0.2.0 independently selects and stabilizes its target. Choosing that alternative changes the later alpha versions and synchronization resolutions; the rest of this concrete walkthrough follows the optional Start choice.
git switch develop
git pull --ff-only origin develop
git fetch origin --tags
git switch -c feature/farewellAdd a real new function to greeting.py:
def farewell(name):
return f"Goodbye, {name}!"Import farewell in the test file and add a test asserting farewell("Ada") == "Goodbye, Ada!". This work belongs to the next cycle, not release 0.2.0.
python -m unittest discover -s tests
git add greeting.py tests/test_greeting.py
git diff --cached
git commit -m "feat: add farewell greeting"
git push -u origin feature/farewell
git fetch origin --tags
git-tools pr --base develop --start-pr --workflow-version 0.3.0Wait for the source workflow: 0.2.0-alpha.1, no new tag. In GitHub create feature/farewell → develop, title Start 0.3.0, with a body describing farewell. Review, pass checks, and squash-merge with final subject Start 0.3.0. Wait for CI: develop becomes 0.3.0-alpha.0, tag 0.3.0-alpha.0. Release is still on 0.2.0-alpha.1.
git switch develop
git pull --ff-only origin develop
git fetch origin --tagsgit switch release/0.2.0
git pull --ff-only origin release/0.2.0
git fetch origin --tagsgit switch -c release-fix/blank-nameOn this release line, change greet to:
def greet(name):
cleaned = name.strip()
return f"Hello, {cleaned or 'friend'}!"Add a test asserting greet(" ") == "Hello, friend!"; keep the previous tests. The farewell function/test should not yet be on this release branch.
python -m unittest discover -s tests
git add greeting.py tests/test_greeting.py
git diff --cached
git commit -m "fix: greet blank names as friend"git push -u origin release-fix/blank-name
git fetch origin --tags
git-tools pr --base release/0.2.0The example version adapter does not run on release-fix/*; no version/tag is produced on this source (separate PR tests still run). In GitHub create release-fix/blank-name → release/0.2.0, title fix: greet blank names as friend. Review the implementation and regression test, wait for checks, and squash-merge with that Conventional Commit subject. Wait for the release-branch version job. Expect 0.2.0-rc.0, tag 0.2.0-rc.0. This is alpha → RC on the same release line, not a patch release.
git switch release/0.2.0
git pull --ff-only origin release/0.2.0
git fetch origin --tagsgit switch -c release-fix/release-notesCreate RELEASE_NOTES.md with a # 0.2.0 heading and accurate bullets for named greetings, trimming, and the blank-name fallback. Do not list farewell; it is next-cycle work. This real reviewable documentation diff gives a second RC checkpoint.
git add RELEASE_NOTES.md
git diff --cached
git commit -m "docs: describe greeting release"git push -u origin release-fix/release-notes
git fetch origin --tags
git-tools pr --base release/0.2.0In GitHub create release-fix/release-notes → release/0.2.0, title docs: describe greeting release. The source is outside the version adapter triggers: no tag. Review the notes, wait for checks, and squash-merge with that subject; wait for release CI. Expect 0.2.0-rc.1, tag 0.2.0-rc.1. A Conventional Commit such as docs: is bump-eligible for RC continuation even though it does not normally select a semantic increment by itself.
git switch release/0.2.0
git pull --ff-only origin release/0.2.0
git fetch origin --tags
git fetch origin master
git merge-base --is-ancestor origin/master HEAD
python -m unittest discover -s testsThe ancestry command must succeed in this serialized story: master is still stable 0.1.0, already contained in the release's history. Do not merge develop/farewell into the release before promotion. A promotion must include current stable master state as well as the RC, not just have an attractive PR title.
If the ancestry check fails because master advanced, pause the serialized timeline and use this reviewed recovery route. First confirm 0.2.0 is still the intended valid release target; otherwise reassess it before proceeding. Use an unused temporary branch name (add a suffix on repeat attempts):
git switch release/0.2.0
git pull --ff-only origin release/0.2.0
git fetch origin master --tags
git switch -c release-fix/sync-master
git merge --no-ff --no-commit origin/masterResolve any conflicts, preserving all stable fixes and the candidate's intended RC version fields in .cz.toml and any managed manifests/lockfiles; do not replace whole manifests to resolve a version. Stage every resolved path and re-test:
git add -u
git diff --cached
python -m unittest discover -s tests
git commit -m "chore: merge master for release"
git push -u origin release-fix/sync-masterIn GitHub, create release-fix/sync-master → release/0.2.0, title chore: merge master for release. Review the synchronization and pass PR checks, then choose Create a merge commit, customizing the final subject to chore: merge master for release, not Merge pull request #.... Do not squash or rebase this inner PR: the merge of master must remain in the candidate's ancestry. Repository and target-branch rules must permit merge commits; retain review requirements and do not push directly to the protected candidate.
Wait for the release-branch version job, then pull its result and verify against freshly fetched master:
git switch release/0.2.0
git pull --ff-only origin release/0.2.0
git fetch origin master --tags
git merge-base --is-ancestor origin/master HEAD
git show HEAD:.cz.toml
python -m unittest discover -s testsThe ancestry check must now succeed before promotion; if master advanced again, repeat the reviewed route on a fresh temporary branch and revalidate the target. An eligible synchronization merge normally advances RC, so use its actual published RC rather than insisting on rc.1. This ancestry-preserving exception is only for current-master synchronization, not the later squash-safe develop/backmerge preparation.
git fetch origin master --tags
git merge-base --is-ancestor origin/master HEAD
git-tools pr --base origin/master --release-prFetching updates origin/master, not local master; promotion helpers therefore explicitly use --base origin/master. If the ancestry check fails, stop and finish the reviewed current-master synchronization above before generating text or promoting. These checks and the hotfix checks below must use current remote state.
In GitHub create release/0.2.0 → master, title Release 0.2.0. Inspect the diff: it contains the greeting and stabilization work, not farewell; .cz.toml carries 0.2.0-rc.1 in this uninterrupted example. Obtain review and green PR checks, squash-merge with final subject Release 0.2.0, and retain the source branch (disable automatic deletion or explicitly keep it).
Wait for master's post-merge version job: stable 0.2.0, tag 0.2.0. Creating or approving the PR alone does not publish stable.
git switch master
git pull --ff-only origin master
git fetch origin --tags
git show HEAD:.cz.toml
git tag --list '0.2.0'Only after stable 0.2.0 is published, integrate current develop into the retained release source. This direction is backmerge preparation, not another promotion. It carries farewell into the source only after release publication. Keep develop's version state 0.3.0-alpha.0 when resolving .cz.toml; preserve the blank-name fix, notes, and all tests when resolving code. This produces a real diff, not an empty "open release" PR.
git switch release/0.2.0
git pull --ff-only origin release/0.2.0
git fetch origin --tags
git fetch origin developgit switch -c release-fix/sync-developgit merge --no-ff --no-commit origin/developIf Git reports conflicts, resolve them before continuing. For this manifest-free example, take the known develop version config while retaining all actual application changes:
git restore --source=origin/develop -- .cz.toml
# Resolve greeting.py/tests manually if needed: retain greet fixes AND farewell.
git add .cz.toml greeting.py tests/test_greeting.py RELEASE_NOTES.md
python -m unittest discover -s tests
git diff --cached
git commit -m "chore: merge develop for backmerge"git push -u origin release-fix/sync-develop
git fetch origin --tags
git-tools pr --base release/0.2.0In GitHub create release-fix/sync-develop → release/0.2.0, title chore: merge develop for backmerge. The source produces no tag. Review the actual farewell integration, version resolution, and retained stabilization fixes; pass checks and squash-merge with that exact subject. Wait for source-line CI. The engine recognizes this exact preparation subject before ordinary release-line validation. It continues the copied alpha to 0.3.0-alpha.1, without a tag. An arbitrary chore: title here is not interchangeable: classic would reject an alpha on the wrong release line. The source is now an integration carrier, not a candidate to promote to master again.
git switch release/0.2.0
git pull --ff-only origin release/0.2.0
git fetch origin --tagsSquash completion does not preserve source ancestry. A naive later PR from the retained source can show already-delivered changes, and squashing a bot's untagged prep version can also lose its history anchor. Use a temporary branch based on current develop, merge the retained release source locally, and preserve develop's current version fields. This keeps the final target diff and version decision deterministic without rewriting either protected branch. The essential safeguard is the proposed version, not the temporary branch name: before squash completion it must still match current develop (0.3.0-alpha.0 here), whose tag remains available. After completion, develop's own CI creates a fresh untagged bump commit that subsequent runs retain in target history. Copying the source's untagged prep alpha.1 into the squash commit instead loses that anchor and can fail even with --yes.
git switch develop
git pull --ff-only origin develop
git fetch origin --tags
git switch -c integration/backmerge-release-0.2.0
git fetch origin release/0.2.0
git merge --no-ff --no-commit origin/release/0.2.0
git restore --source=origin/develop -- .cz.tomlResolve any remaining application/test conflicts: the final tree must include farewell, trimming, the blank-name fallback, and release notes. Stage every resolved path; do not replace an entire manifest merely to change its version in a packaged application.
git add .cz.toml greeting.py tests/test_greeting.py RELEASE_NOTES.md
python -m unittest discover -s tests
git diff --cached
git commit -m "chore: integrate released greeting fixes"
git push -u origin integration/backmerge-release-0.2.0
git fetch origin --tags
git diff origin/develop...HEAD
git-tools pr --base develop --backmerge-release-pr --workflow-version 0.2.0Source: integration/backmerge-release-0.2.0 (carrying retained release/0.2.0) → target: develop; title: Backmerge Release 0.2.0. The integration branch is outside the example adapter's push triggers: no version/tag there; it still runs applicable PR checks. .cz.toml in its proposed target tree remains 0.3.0-alpha.0 before completion.
Create that PR in GitHub, review the actual unique stabilization diff and passing tests, then squash-merge with final subject Backmerge Release 0.2.0. Wait for develop CI. The blank-name fix and notes are meaningful new content relative to develop's first-parent state, so expect 0.3.0-alpha.1, no tag. This happens independently of the prep branch's untagged alpha.1.
git switch develop
git pull --ff-only origin develop
git fetch origin --tags
git show HEAD:.cz.toml
git tag --list '0.3.0-alpha.*'At this point only 0.3.0-alpha.0 is tagged on that line. Version-only/no-op backmerges do not advance alpha; a develop line not yet ahead can instead catch up/finalize to the promoted stable version without a tag. Do not expect a new tag from either backmerge kind. Once the real fixes are confirmed on develop, the release source and temporary branches can be deleted; retain hotfix/* similarly until its own backmerge finishes. Do not repeatedly reuse a squash-promoted branch for later releases.
Before beginning the hotfix, publish a normal next-cycle checkpoint. This matters particularly for reviewed develop synchronization completed with squash: copying an untagged develop version into a squash commit can drop the original bot history anchor. A tagged checkpoint avoids that problem without direct pushes or fabricated tags.
git switch -c feature/farewell-docsCreate NEXT_CYCLE.md documenting the actual farewell API and its planned 0.3.0 delivery. This is next-cycle documentation, not a modification to the published 0.2.0 release notes.
git add NEXT_CYCLE.md
git diff --cached
git commit -m "docs: document next-cycle farewell"
git push -u origin feature/farewell-docs
git fetch origin --tags
git-tools pr --base developThe source workflow skips: still 0.3.0-alpha.1, no tag. In GitHub create feature/farewell-docs → develop, title docs: document next-cycle farewell. Review the real documentation diff, pass checks, and squash-merge with that subject. Wait for develop CI: normal develop commits use a default patch increment, so this continues to 0.3.0-alpha.2, tag 0.3.0-alpha.2.
git switch develop
git pull --ff-only origin develop
git fetch origin --tagsNow the next synchronization can resolve its copied version against the published 0.3.0-alpha.2 tag even if a squash does not retain develop's bump commit. Do not manually tag the earlier no-tag backmerge state.
git switch master
git pull --ff-only origin master
git fetch origin --tags
git switch -c hotfix/missing-name
git push -u origin hotfix/missing-nameTransition: stable master 0.2.0 → new hotfix/missing-name, no PR/title and no new human content. Wait for the workflow: no unique hotfix commit yet, so 0.2.0, no new tag.
git switch -c hotfix-fix/missing-nameFix the production error for None input. On this hotfix branch greet should become:
def greet(name):
cleaned = (name or "").strip()
return f"Hello, {cleaned or 'friend'}!"Add a regression test asserting greet(None) == "Hello, friend!". Farewell is not on stable master yet and must not be introduced by this hotfix.
python -m unittest discover -s tests
git add greeting.py tests/test_greeting.py
git diff --cached
git commit -m "fix: handle missing greeting names"git push -u origin hotfix-fix/missing-name
git fetch origin --tags
git-tools pr --base hotfix/missing-nameIn GitHub create hotfix-fix/missing-name → hotfix/missing-name, title fix: handle missing greeting names. No source version/tag is produced (hotfix-fix/* is outside adapter triggers). Review the implementation/test, pass checks, and squash-merge with that subject; wait for hotfix CI. Expect 0.2.1-rc.0, tag 0.2.1-rc.0. The hotfix selects the next patch from stable master, not from develop's 0.3.0 line.
git switch hotfix/missing-name
git pull --ff-only origin hotfix/missing-name
git fetch origin --tags
git fetch origin master
git merge-base --is-ancestor origin/master HEAD
python -m unittest discover -s testsThe master ancestry check succeeds in this serialized story: hotfix contains stable 0.2.0. If master has advanced, pause promotion and reassess its next-patch target first. If that boundary changed, re-plan the hotfix from the new stable base and obtain a valid patch RC through reviewed stabilization and CI; do not force the old target or RC. Once the intended patch RC is valid, synchronize current master through a reviewed inner PR, using an unused temporary branch name:
git switch hotfix/missing-name
git pull --ff-only origin hotfix/missing-name
git fetch origin master --tags
git switch -c hotfix-fix/sync-master
git merge --no-ff --no-commit origin/masterResolve any conflicts, retaining all stable fixes and the intended valid patch RC fields in .cz.toml and any managed manifests/lockfiles. Stage every resolved path, review the diff, and re-test:
git add -u
git diff --cached
python -m unittest discover -s tests
git commit -m "chore: merge master for hotfix"
git push -u origin hotfix-fix/sync-masterIn GitHub, create hotfix-fix/sync-master → hotfix/missing-name, title chore: merge master for hotfix. Obtain review and passing checks, then choose Create a merge commit, customizing its final subject to chore: merge master for hotfix. Do not squash or rebase: current master's ancestry must survive this inner PR. Ensure repository and target-branch rules allow merge commits; do not bypass review with a direct human push. Wait for the hotfix-branch version job, then:
git switch hotfix/missing-name
git pull --ff-only origin hotfix/missing-name
git fetch origin master --tags
git merge-base --is-ancestor origin/master HEAD
git show HEAD:.cz.toml
python -m unittest discover -s testsThe ancestry check must succeed before promotion. If master advanced again, reassess the next-patch target and repeat the reviewed route on a fresh temporary branch as needed. Use the actual RC produced by CI, not necessarily the serialized example's 0.2.1-rc.0. This current-master exception does not change the later squash-safe develop/backmerge preparation.
Refresh the promotion base again; if ancestry fails or the next-patch target changed, stop and return to the synchronization/reassessment route above:
git fetch origin master --tags
git merge-base --is-ancestor origin/master HEAD
git-tools pr --base origin/master --hotfix-prIn this uninterrupted example, create hotfix/missing-name → master in GitHub, title Hotfix 0.2.1. The proposed tree must carry 0.2.1-rc.0, the missing-name fix and regression test, and current stable master state, but not farewell. Review, pass checks, and squash-merge with final subject Hotfix 0.2.1. Keep the hotfix source branch.
Wait for master CI: stable 0.2.1, tag 0.2.1.
git switch master
git pull --ff-only origin master
git fetch origin --tags
git show HEAD:.cz.toml
git tag --list '0.2.1'Only after stable publication, integrate develop into the retained hotfix source. Develop is now the tagged 0.3.0-alpha.2 checkpoint. Keep that version config, retain the missing-name fix and all develop work, and never promote this combined source to master again.
git switch hotfix/missing-name
git pull --ff-only origin hotfix/missing-name
git fetch origin --tags
git fetch origin developgit switch -c hotfix-fix/sync-developgit merge --no-ff --no-commit origin/develop
git restore --source=origin/develop -- .cz.tomlResolve conflicts in code/tests by retaining both the None fallback and farewell. Stage all resolutions, then:
git add .cz.toml greeting.py tests/test_greeting.py RELEASE_NOTES.md
python -m unittest discover -s tests
git diff --cached
git commit -m "chore: merge develop for backmerge"git push -u origin hotfix-fix/sync-develop
git fetch origin --tags
git-tools pr --base hotfix/missing-nameIn GitHub create hotfix-fix/sync-develop → hotfix/missing-name, title chore: merge develop for backmerge. This is a real synchronization diff (including farewell), not an empty PR. No version/tag on the source. Review, pass checks, and squash-merge with that exact subject; wait for the hotfix-branch version job. Expect the copied alpha to continue to 0.3.0-alpha.3, no tag, via the special prep rule. This rule is important: normal hotfix validation would reject a 0.3.0 version against stable 0.2.1.
git switch hotfix/missing-name
git pull --ff-only origin hotfix/missing-name
git fetch origin --tagsAgain prepare a squash-safe integration branch from develop, keeping develop's pre-merge version 0.3.0-alpha.2 rather than copying the source's untagged prep version:
git switch develop
git pull --ff-only origin develop
git fetch origin --tags
git switch -c integration/backmerge-hotfix-0.2.1
git fetch origin hotfix/missing-name
git merge --no-ff --no-commit origin/hotfix/missing-name
git restore --source=origin/develop -- .cz.tomlResolve any application/test conflicts, preserving the None regression fix and all next-cycle work. Stage all resolutions:
git add .cz.toml greeting.py tests/test_greeting.py RELEASE_NOTES.md
python -m unittest discover -s tests
git diff --cached
git commit -m "chore: integrate published missing-name fix"
git push -u origin integration/backmerge-hotfix-0.2.1
git fetch origin --tags
git diff origin/develop...HEAD
git-tools pr --base develop --backmerge-hotfix-pr --workflow-version 0.2.1The explicit --workflow-version 0.2.1 means the already-promoted hotfix, not master's next patch and not the source's synchronized alpha. The helper intentionally does not infer it.
In GitHub create integration/backmerge-hotfix-0.2.1 → develop (carrying retained hotfix/missing-name), title Backmerge Hotfix 0.2.1. The integration source produces no version/tag. Inspect the target diff: it must contain the new missing-name fix, retain farewell, and propose 0.3.0-alpha.2 before CI. Review, pass checks, squash-merge with that final subject, and wait for develop CI: meaningful unique fixes yield 0.3.0-alpha.3, no tag.
git switch develop
git pull --ff-only origin develop
git fetch origin --tags
python -m unittest discover -s tests
git show HEAD:.cz.tomlVerify the fix is present before deleting the hotfix and temporary integration branches. Backmerge titles must never be Release 0.2.0 or Hotfix 0.2.1 on develop: those titles are promotion-only and are rejected there. As with the release backmerge, no-op/version-only changes would skip rather than advance alpha.
Develop is now on 0.3.0-alpha.3; master is stable 0.2.1. Make one more real fix:
git switch -c bugfix/trim-farewellEdit farewell to return f"Goodbye, {name.strip()}!". Add a test asserting farewell(" Ada ") == "Goodbye, Ada!", retaining all greeting regression tests.
python -m unittest discover -s tests
git add greeting.py tests/test_greeting.py
git diff --cached
git commit -m "fix: trim farewell names"
git push -u origin bugfix/trim-farewell
git fetch origin --tags
git-tools pr --base developWait for the bugfix source job: no bump/tag, still 0.3.0-alpha.3. In GitHub create bugfix/trim-farewell → develop, title fix: trim farewell names; review, pass checks, and squash-merge with that subject. Wait for develop CI: 0.3.0-alpha.4, tag 0.3.0-alpha.4. The absence of alpha.1/alpha.3 tags is intentional: those were no-tag backmerge states, with generated bump commits as history anchors.
git switch develop
git pull --ff-only origin develop
git fetch origin --tags
git switch -c release/0.3.0
git push -u origin release/0.3.0Transition: current develop → next release/0.3.0; no PR/title, no unique human change yet, no new tag, still 0.3.0-alpha.4. Wait for the skip job. You are now at the next release cut. Release-led validates 0.3.0 as the next minor step from stable master 0.2.1; the patch hotfix did not force the next release to 0.2.2. To repeat this example's optional explicit next-cycle choice (not a release-led requirement), a real feature PR titled Start 0.4.0 opens 0.4.0-alpha.0 on develop, while a real stabilization change on release opens 0.3.0-rc.0. Use reviewed release-fix/* inner PRs, including any synchronization, just as above. Then promote, wait for stable, and backmerge before deleting the source.
The engine's behavior is covered by tests/test_git_flow_strategy.py, tests/test_backmerge_content.py, and tests/test_hotfix_backmerge.py; implementation is in git_tools/generators/bumpgen/{strategy,rules,repo}.py. Backmerge content is compared against the target commit's first parent, ignoring only actual managed version-field changes, not whole manifests or lockfiles. Different diffs, subjects, merge styles, extra CI-producing pushes, stale refs, or a different remote engine ref can legitimately change the result. Check .cz.toml, bot commits, remote refs, and tags at each checkpoint rather than manufacturing a missing tag or asserting that opening a PR performed a release.
Release-led reviewed combines release-branch version selection with review of every human stabilization/synchronization change. It is a repository policy, not a compliance certification. Commands run in your application checkout.
Ordinary Conventional Commit PRs into develop create/continue tagged alpha versions. Reviewed mode adds inner PRs to release/hotfix lines, not an extra layer on develop. A first real PR may optionally use Start X.Y.Z, with Conventional Commit branch commits.
Use a canonical ASCII X.Y.Z that is exactly the next PATCH, MINOR, or MAJOR step from stable master. On opening, this absolute tuple wins over a carried alpha/beta, even when it is lower: master 0.1.0 with source 0.2.0-alpha.1 and release/0.1.1 opens 0.1.1-rc.0. A stable source can open a forward target only from master's tuple. A different established RC or a stable source not on master's tuple is refused before version writes; same-line RCs continue rather than reset. The configured scheme is preserved (-rc.0 for semver2, -rc0 for semver). See absolute target calculation.
release/X.Y.Z selects the final target, validated against stable master. Cutting it alone does not open RC or require a Start PR; develop can continue its alpha line independently. The example's Start 0.3.0 is optional next-cycle selection, not a requirement after the cut.
When you explicitly want a new develop line, use a real feature/bugfix branch and git-tools pr --base develop --start-pr --workflow-version A.B.C with a valid forward tuple. Complete it as Start A.B.C for tagged A.B.C-alpha.0; do not use a Backmerge title to select a new cycle.
This mode uses squash for ordinary PRs, promotions, and develop/backmerge preparation. Current-master synchronization before promotion is the narrow exception: complete that reviewed inner PR with Create a merge commit, not squash or rebase, so master's ancestry survives. Enable repository merge commits and permit them in release/hotfix target rules; a strict squash-only or linear-history policy on those targets is incompatible with this route. Customize the final subject to chore: merge master for release or chore: merge master for hotfix. Other release/hotfix inner subjects must also be Conventional Commits; a factory-default Merge pull request #... subject does not follow this convention, but a Conventional Commit line in its body can still make the merge bump-eligible and advance RC because eligibility scans the full commit message. The engine ignores GitHub's optional trailing (#123) suffix.
Require human PRs into master, develop, release, and hotfix targets. Only automation gets the approved narrow signed-version push exception. Prepare synchronization on a temporary release-fix/* or hotfix-fix/* branch based on the target source line, then submit an inner PR back into it. For current-master synchronization, preserve the intended valid RC fields and stable fixes, review/test, and complete with Create a merge commit using the stated Conventional Commit subject. Wait for CI, pull its result, fetch master again, and require git merge-base --is-ancestor origin/master HEAD to succeed before promotion. Reassess a changed hotfix next-patch target. Develop synchronization for backmerge instead retains its documented squash-safe version resolution.
Never push synchronization directly to a protected source line. An empty commit alone is not a mergeable GitHub inner PR: use a real reviewable diff or an approved auditable initialization procedure.
The release branch selects the tuple. Its first real inner PR with an eligible Conventional Commit title opens X.Y.Z-rc.0; later ones continue that RC line. Use release-fix/<name> and one focused logical change per PR. An inner chore: open release is acceptable only with a real reviewable diff. Reserve promotion/backmerge fixed titles for boundary PRs, not ordinary inner fixes.
Include the expected RC and current master, synchronizing master through an inner PR and re-testing if needed. Promote into master with Release X.Y.Z, and wait for stable publication before backmerge.
Use Backmerge Release X.Y.Z for the develop boundary PR. Preserve an ahead alpha; meaningful unique fixes advance it once without a tag. No-op/version-only changes do not advance it. Develop not yet ahead may instead catch up to promoted stable without a tag; open a later real cycle with Start A.B.C when wanted.
Follow the reviewed source synchronization and develop-based integration PR. Squash does not preserve source ancestry. Keep develop's pre-merge version in the integration diff only when its alpha release tuple is ahead of the promoted target, not the source's untagged prep version; resolve .cz.toml and managed manifest versions consistently, not by lexical string order. Otherwise use the stable-catch-up procedure.
The numbered 0.3.0-alpha.* backmerge is the ahead-alpha case only. Compare numeric release tuples, not prerelease counters or lexical strings: 0.2.0-alpha.N is not ahead of promoted stable 0.2.0. This procedure also applies to hotfix backmerges when develop is not ahead of the promoted patch.
- Finish promotion and fetch its existing stable tag. Complete the retained source's synchronization through the permitted direct or reviewed lane. Wait for any no-tag preparation job and pull its result. That source version is intermediate: setting stable before the exact
chore: merge develop for backmergesubject is not sufficient, because its special rule can open another RC. - Update develop, fetch tags, and create a fresh
integration/*branch from develop, as in the numbered integration recipe. Merge the retained prepared source withgit merge --no-ff --no-commit <source-ref>, replacing<source-ref>with the fetched release/hotfix ref. Retain all published fixes and continued develop work. - Before committing this integration, resolve only the managed version fields in
.cz.tomland synchronized manifests/lockfiles to the already-published stable targetX.Y.Z, not develop's same-line alpha or the source's preparation version. Preserve all other settings, dependencies, and application changes; do not restore whole manifests from master. For example, backmergingRelease 0.2.0into0.2.0-alpha.Nmust propose stable0.2.0at the develop boundary. - Test and commit the integration, push it, and open its reviewed PR into develop with final title
Backmerge Release X.Y.ZorBackmerge Hotfix X.Y.Z. Generate the title using the matchinggit-tools pr --base develop --backmerge-release-pr --workflow-version X.Y.Zor--backmerge-hotfix-pr --workflow-version X.Y.Z. ReplaceX.Y.Zwith the historical promoted target. Squash-merge as in the numbered GitHub recipe; never promote this integration to master. - Verify develop contains the fixes and stable
X.Y.Z. Its version job skips because the boundary already matches stable, including version-only backmerges; it must not advance the old alpha or create another stable tag. Open the next cycle later with a realStart A.B.CPR. The alternate histories are covered bytests/test_backmerge_catchup.py.
Start hotfix/<name> from published stable master. Every human change, including a single-fix hotfix, uses hotfix-fix/<sub-name> → hotfix/<name> with a Conventional Commit title. Creating the branch alone does not open RC; the first eligible inner PR opens the next patch rc.0, and later ones continue it. An empty commit alone is not an initialization PR: use a real diff or approved procedure. Do not use Hotfix X.Y.Z or Backmerge Hotfix X.Y.Z for ordinary inner fixes.
Synchronize changed master through an inner PR, re-test, and reassess a changed patch target. Promote into master with Hotfix X.Y.Z, then wait for stable publication.
Use Backmerge Hotfix X.Y.Z into develop. The helper requires --workflow-version for the already-promoted patch, not master's next patch or the synchronized source alpha. The release-backmerge rules for ahead alpha, stable catch-up, no-op, no tag, and consistent version resolution also apply. Follow the reviewed hotfix synchronization and develop integration PR; never promote the combined source again.