| Branch | Change path | Release responsibility |
|---|---|---|
develop |
Repository default and base for ordinary feature, fix and CI pull requests. Keep topic branches short lived. | Next feature line, ordinary CI and trusted default-branch workflows. |
release/X.Y |
Seed from a reviewed develop commit when the feature set freezes. Target only stabilization changes to this line. |
Qualify the candidate with the full release matrix of its promotion PR to main while development continues. |
main |
Promote a reviewed release branch by pull request. | Production history and publication point for the latest stable line. |
support/X.Y |
Exists only for an approved patch on an earlier line. Seed it from that line's latest published stable tag and make the patch by PR. | Publish that one patch. Keep its tags on that line. The line does not become the latest and gets no routine fixes. |
A maintainer records a COMMENT review of the exact PR head, addresses findings and resolves review threads before merge. The repository has a single maintainer. GitHub requires a pull request and resolved conversations, with the minimum approval count set to zero. Checking that the COMMENT review exists and still applies is the maintainer's responsibility. A reviewer who needs extra native coverage before the merge requires it with /ci require and checks the Required requested CI status of the exact head, as described in Requiring requested CI before a merge. Every maintained branch requires the six GitHub Actions Code check contexts. Where the optional ruleset Git Flow / requested CI is installed, every maintained branch also requires Required requested CI from GitHub Actions; git_flow.py plan --requested-ci and apply --requested-ci install it as described in Enabling the branch rule, and verify checks it only when it exists. Main and each registered release and support branch also require an up-to-date candidate and a successful Release candidate validated (<target branch>) from GitHub Actions. Moving the base invalidates stale candidate CI. No ruleset grants a bypass.
At the v1.0.0 baseline, the published tag and main both pointed to 43a17659bbd60776f987b773d68fe24011cd7220. Only main existed among the maintained branches. Its active repository ruleset required PRs, resolved threads, zero approvals and the six Actions Code checks (app ID 15368). All six succeeded at that SHA. Main and scenario-history already blocked non-fast-forward updates and deletion. There was no release tag ruleset. The GitHub release reported immutable: false. A tag update/deletion rule protects the Git ref independently of GitHub Release assets and notes.
Run the commands from this repository with an authenticated gh. Planning reads GitHub and prints the proposed API payloads. Applying requires repository administration and permission to create refs. Run one cutover or line-registration operation at a time. Keep existing protections in place.
-
Merge the reviewed policy PR to
mainunder the previous rules. Keepmainas the default during initial bootstrap. The policy merge is a bootstrap commit after v1.0.0. Leave the published tag at its original SHA. -
Wait for the Code and Release matrix push workflows on that merge commit to finish. Review their jobs, attempt IDs and native reports. The initial apply checks that the current main tip is that PR's merge, the merged PR delivered this tool, the v1.0.0 tag is intact, and the executable matches the merged file. If another commit lands first, stop and reconcile the cutover point.
-
From the merged checkout, run the plan and then substitute the merged policy PR number in the apply command.
python3 scripts/release/git_flow.py plan python3 scripts/release/git_flow.py apply --policy-pr <number> python3 scripts/release/git_flow.py verify
The tool adds its own rulesets, leaves the existing history and main rulesets in place, prohibits creation of unregistered release/support lines, and seeds
developat the policy merge. The catch-all maintained-branch rule blocks force pushes and deletion. The tag rule blocks updates and deletion ofv*tags. It permits creation of a new release tag. Verify reads back active repository rulesets and each maintained branch's effective rules, including the unregistered-line creation guard. GitHub exposes effective rules for branch names; tag protection is checked through the active tag ruleset's target, exact pattern, rules and empty bypass list. -
List in-flight PRs with
gh pr list --state open --base main. Retarget development work individually withgh pr edit <number> --base develop. Keep only intentional production promotions on main. Recheck the diff, review and required runs at the new base. A base edit alone may not trigger every workflow. Reopen the PR or push its reviewed update to obtain the new target's checks before merging. Verify the effective rules on both branches and the scheduled workflows, CI command and structural publisher on protecteddevelop. Switch the GitHub default withgh repo edit --default-branch developand confirm withgh repo view --json defaultBranchRefandpython3 scripts/release/git_flow.py verify. New ordinary PRs then targetdevelopby default. Release promotions explicitly select--base main. Existing clones can refresh their remote HEAD withgit remote set-head origin -a.
If an API write fails, rerun the same command after checking its plan and the live refs. Equal rulesets and matching branch seeds are reused. A registration retry checks the existing ref against the requested seed, including after the creation guard has been updated. Use verify for routine rules checks after a branch advances. A conflicting ruleset, existing ref at another SHA, or unexpected managed line requires reconciliation. The tool never resets a branch, rewrites the original main or history rulesets, publishes a tag, or retargets a PR.
To freeze a feature line, use plan and apply with the same line and source, then run verify. The plan shows the current seed SHA. Pass this exact SHA to apply with --at. A changed source requires a new plan. A line's exact candidate rule is installed and inspected before its name is released from the wildcard creation guard. Unregistered names remain reserved.
python3 scripts/release/git_flow.py plan --line release/1.1 --from develop
python3 scripts/release/git_flow.py apply --line release/1.1 --from develop --at <planned-seed-sha>
python3 scripts/release/git_flow.py verifyOrdinary fixes land on develop with their regression coverage. The maintainer checks the maintained line, the latest published stable one, and any active stabilization line against the original defect. For each affected target, branch from its tip, cherry-pick the fix and tests with git cherry-pick -x <fix-commit>, adapt them as needed, and open a PR against that target. Record the source PR, target PRs and the reason for skipping unaffected lines. Skip fixes already present. Features and API removals stay on the development path under the compatibility policy.
For example, accumulate approved 1.0.x fixes on release/1.0 while 1.1 development continues. When the maintainer chooses to ship, promote that branch to main, qualify the resulting commit and tag it v1.0.1. The branch is reused for later patches. Freeze release/1.1 from develop when the 1.1 feature set is ready.
For an urgent production patch, branch from the latest published tag on the production line or from its matching main tip. Target a PR at that line's existing release branch. If no such branch exists, register it with e.g. --line release/1.1 --from v1.1.0. Advance an existing release line through a reviewed synchronization PR from production if it lacks a production fix. Keep released branches protected after promotion, and reuse the line for later patches without resetting it. Promote the patch by a release-to-main PR. During stabilization on a newer release branch, propagate the fix there immediately and forward to develop. Propagate stabilization fixes to develop by PR as they land.
When the next feature release becomes production, the preceding line stops receiving routine patches and no support branch is seeded for it. Its tags, refs and protections stay. Only an approved patch on an earlier line registers that line, with e.g. --line support/1.0 --from v1.0.4, substituting its actual last stable tag. Both plan and apply check the highest published stable patch number on that line. If a new patch ships between them, plan again from its tag. Publish the patch from its checked support merge and do not mark its GitHub Release as the latest. Open separate forward-port PRs to the current production release line, any active stabilization line, and develop wherever the defect is present. Record the original fix commit and destination PRs. Afterwards keep the support branch's refs and protections for provenance and stop accepting updates. An older line may predate these workflows. Its initial reviewed tooling PR must bring in the candidate validation before it can pass the line's required checks.
Use merge commits for maintained-branch PRs so the promoted branch remains in history. A publication PR's test merge, its head, and the actual production or support merge can have different SHAs. Freeze the post-merge SHA on the publishing branch and qualify that exact SHA via its own push workflows. Its Code checks always run on it. Its Release matrix push run either executes the full matrix or, on main, reuses the promotion PR's run when the test merge and the protected merge have the same tree and parents. The read-only evidence command requires that the SHA is still the branch tip, confirms the workflow path, push event, branch, commit, run and attempt, and checks the successful named jobs on that attempt. For main it also reports which of the two qualified the commit, and for a reuse it verifies the promotion run, its candidate receipt, the preserved job records and the tested commit again from the repository, requires the publication run's own copy of those records to be the file that qualified it, and prints the source run, the tested commit, the number of job records and the number of first failures that a retry passed. Review native artifacts and earlier failed attempts as described in Preparing a release.
python3 scripts/release/git_flow.py evidence --branch main --sha <full-production-merge-sha>
# For an approved patch on an earlier line use --branch support/X.Y and its actual merge SHA.Create the new tag on that literal full SHA and publish its GitHub Release following the release guide. Verify the peeled remote tag equals the qualified commit. If the candidate changes, repeat qualification. Preserve every previously published tag. Following a production merge, reconcile its history and fixes into develop and affected stabilization branches by PR.
The administrative API semantics are described in GitHub repository rulesets and workflow runs.