Git Release Start

Overview

At the start of a version iteration, create a release branch from the main development branch. Core principle: create on remote first, then sync to local — git checkout -b release/X origin/master makes the local branch track origin/master instead of origin/release/X, planting a landmine for later push/pull confusion.

Pairing: git-release-start (iteration start, this skill) ↔ git-release-finish (iteration end, tag + merge).

Platform CLI mapping

Convention: <GIT_CLI> below stands for the platform's CLI tool — pick the row above that matches your environment, or the equivalent command for other platforms. Core git operations (fetch, checkout) are platform-agnostic.

Use when / Do not use for

Use when:

• A version iteration starts and a new release branch needs to be created from the main branch
• Multiple repos need release branches for the same version, created in a coordinated way
• The branch's tracking must be verified correct (not accidentally pointing at master/main)
• An existing release-branch naming convention exists and must be followed

Do not use for:

• Non-Git hosting platforms

Principle: the flow must run end-to-end. No phase can be skipped, regardless of repo count. "It's just creating a branch" is the most common cause of skipping verification and ending up with wrong tracking.

Pre-conditions

• The corresponding platform CLI is installed and authenticated
• The version number is confirmed (e.g. 8.2.70)
• The base branch is confirmed (e.g. master or main)

Phase map

Phase 1: Confirm version number and base branch

⚠️ Confirm before creating, to avoid creating the wrong version or basing off the wrong branch.

1.1 Version number confirmation

If the user's message already states the version number, use it directly without asking again. Otherwise confirm with the user:

• The new version number (e.g. 8.2.70)
• The previous version number (used in Phase 2 to compare historical branch naming, e.g. 8.2.60)

Checks:

• Whether the new version's tag already exists: git ls-remote origin refs/tags/<TAG_PATTERN>
• Whether the new version's release branch already exists: git ls-remote origin refs/heads/release/<VERSION>
• If it already exists, abort with an error and ask whether to reuse it or rename

1.2 Base branch confirmation

Which branch should the release branch be created from? Usually the main development branch.

# Confirm the base branch exists and is up to date
git fetch origin <BASE_BRANCH>
git log --oneline origin/<BASE_BRANCH> -3

⚠️ Remote HEAD may point at a deprecated branch: after repo migrations or branch-policy changes, remote HEAD may still point at the old main branch (e.g. master) while the actually active main branch has become main. If the branch remote HEAD points to is hundreds of commits behind another candidate branch, HEAD is stale. Trust merge history (git log --merges | grep "into 'main'") as the source of truth, and confirm with the user if needed.

Output: confirmation table (Phase 1 only confirms version number and base branch; the release branch name is determined after Phase 2's analysis)

After confirmation, proceed to Phase 2 (analyze release-branch naming convention).

Phase 2: Analyze release-branch naming convention

⚠️ Release-branch naming may not be simply release/X.Y.Z — check history. This phase outputs the final branch name; only after it completes can Phase 3 create the branch.

# List existing release branches
git branch -r | grep "origin/release"

Identification rules

Multi-product repos: each product line has its own release-branch naming; only create the branch for the current product line this time.

Output: confirmation table

Align with the user on the branch name before executing Phase 3.

Phase 3: Create the release branch on remote

⚠️ Core lesson: must create on remote first, then sync to local. Do not create locally first and push.

Reason: a local branch created with git checkout -b release/X origin/master tracks origin/master instead of origin/release/X, causing confusion in later pushes and pulls.

Run in parallel for all repos:

# GitLab — create the branch on remote via API (`:fullpath` auto-resolves inside the repo directory)
glab api --method POST \
  "projects/:fullpath/repository/branches?branch=<RELEASE_BRANCH>&ref=<BASE_BRANCH>"

# GitHub — `:owner/:repo` auto-resolves when `gh` runs inside the repo directory
BASE_SHA=$(git rev-parse origin/<BASE_BRANCH>)
gh api repos/:owner/:repo/git/refs \
  -f ref="refs/heads/<RELEASE_BRANCH>" \
  -f sha="$BASE_SHA"
# If auto-resolution fails, substitute the actual values manually, e.g.: gh api repos/myorg/myrepo/git/refs ...

Parameters:

• branch: the full name of the new release branch (including path, e.g. release/8.2.70)
• ref / sha: which branch to create from (the main development branch)
• :fullpath: auto-resolved by GitLab; GitHub requires manually substituting :owner/:repo

Phase 3.5: Read release protection

After the remote branch exists, load git-branch-protect when it is available. It reads the live rules with glab or gh and compares them with two conditions: unmatched release/* branches deny push and deny merge, and this exact branch denies push and allows maintainer merge.

A decline leaves the rules unchanged and the release continues. This phase does not write trunk rules and does not run set-trunk. Phase 6 treats a rejected push as success when the protection report says this branch denies push and allows maintainer merge. That report may be already-met or an accepted allow-merge.

Phase 4: Sync locally + set tracking

⚠️ Use --track to ensure the local branch tracks origin/<RELEASE_BRANCH>.

Run in parallel for all repos:

git fetch origin <RELEASE_BRANCH>
git checkout -b <RELEASE_BRANCH> --track origin/<RELEASE_BRANCH>

Verify tracking:

git branch -vv | grep '^\*'
# Expected output: * release/8.2.70  <SHA> [origin/release/8.2.70] <commit message>

If [origin/master] appears in the tracking column: the branch was created the wrong way; fix it with git branch -u origin/release/8.2.70.

Phase 5: Update environment file

Some repos need the current branch name recorded in a release-branch file (which CI scripts etc. may read).

echo "<RELEASE_BRANCH>" > release-branch
git add release-branch
git commit -m "chore: update release-branch to <RELEASE_BRANCH>"

Note: if the repo doesn't use a release-branch file (no historical commits for it), skip this step.

# Check whether this file has existing history
git log --oneline -- release-branch | head -3

Phase 6: Verify

Run the following verification for each repo:

git push --dry-run origin <RELEASE_BRANCH>
# Pass when the protection report says push is denied and maintainer merge is allowed: the push is rejected
# Pass when that report is absent, or the user declined a write and push is still allowed: the dry-run shows the update, or "Everything up-to-date"
# When the user declined a write and the push is still rejected, record the dry-run and continue. Leave the protection rules unchanged

If a check other than this push dry-run fails, stop and fix it; only proceed to Phase 7 after confirming. A rejected dry-run is a pass when the protection report says this branch denies push and allows maintainer merge. A declined write does not turn that rejection into a failure, and it does not authorize a protection change.

Phase 7: Output report

Generate a confirmation table:

Error handling

Common mistakes

Quick reference commands

# List existing release branches
git branch -r | grep "origin/release"

# GitLab — create on remote
glab api --method POST "projects/:fullpath/repository/branches?branch=<NAME>&ref=<BASE>"

# GitHub — create on remote
gh api repos/<OWNER>/<REPO>/git/refs -f ref="refs/heads/<NAME>" -f sha="$(git rev-parse origin/<BASE>)"

# Sync locally
git fetch origin <NAME>
git checkout -b <NAME> --track origin/<NAME>

# Fix tracking (if pointed wrong)
git branch -u origin/<NAME>

# Update release-branch
echo "<NAME>" > release-branch

# Verify
git branch --show-current
git branch -vv | grep '^\*'
git ls-remote origin refs/heads/<NAME>
git push --dry-run origin <NAME>