SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgit-release-start

git-release-start

General & other

View repository

Updated 10-15 21:47

About this skill

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

Platform CLI tool Create branch on remote
GitLab (SaaS / self-hosted) glab glab api POST "projects/:fullpath/repository/branches?branch=<NAME>&ref=<BASE>"
GitHub gh gh api repos/:owner/:repo/git/refs -f ref=refs/heads/<NAME> -f sha=<BASE_SHA>

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 Operation Key tools
1 Confirm version number and base branch —
2 Analyze each repo's release-branch naming convention git branch -r
3 Create the release branch on remote <GIT_CLI> api
4 Sync locally + set tracking git fetch + git checkout --track
5 Update environment file echo / text write
6 Verify git branch + cat
7 Output report —

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)

Repo Version Base branch
repo-A 8.2.70 master

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

Historical branch pattern Naming convention
origin/release/8.2.60, origin/release/8.2.52 release/{VERSION}
origin/release/8.2.60-perf release/{VERSION}-perf
origin/release/mobile-7.5.720 release/mobile-{VERSION} (product prefix)

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

Repo Release branch name Historical example
repo-A release/8.2.70 release/8.2.60
repo-B release/8.2.70-perf release/8.2.60-perf

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 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:

# Push channel is clear (no permission errors is enough)
git push --dry-run origin <RELEASE_BRANCH>
# Expected: shows what would be pushed, or "Everything up-to-date"; no "rejected" or permission errors

If any check fails, stop and fix it; only proceed to Phase 7 after confirming.

Phase 7: Output report

Generate a confirmation table:

Repo Remote branch Local tracking release-branch Status
repo-A origin/release/8.2.70 [origin/release/8.2.70] release/8.2.70 ✅
repo-B origin/release/8.2.70-perf [origin/release/8.2.70-perf] N/A ✅

Error handling

Scenario Handling
Tag already exists Abort with an error; may indicate a duplicate release
Release branch already exists (remote) Ask whether to reuse it (checkout directly) or rename
Base branch doesn't exist Abort with an error, ask for the correct base ref
glab api returns 401 / 403 Check glab auth status, re-authenticate
Tracking points to the wrong branch ([origin/master]) Fix with git branch -u origin/<RELEASE_BRANCH>
A local branch with the same name already exists git branch -D <NAME> to delete it locally, then checkout again
push --dry-run fails Check the remote URL and permissions

Common mistakes

❌ Wrong ✅ Right Consequence
git checkout -b release/X origin/master then push Create on remote via <GIT_CLI> api → fetch → --track Tracking points to origin/master, causing confusion in later pull/push
Create the branch locally first, then push to remote Create the branch on remote first, then fetch to local Same as above
Skip Phase 5's check/update of release-branch Confirm and update it CI may read the wrong release-branch value
Assume all repos use the same naming Check historical branch names per repo Some repos' branch names carry special suffixes (e.g. -perf) and get missed
Consider the task done without verifying tracking Verify each item in Phase 6 Wrong tracking only surfaces later, during merge/push

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>