Git Branching Strategy

Git Branching Strategy

Trigger: Use when setting up or selecting a git branching model for a project or team.

Branching Models

1. GitHub Flow (simplest — recommended for CI/CD)

main ──── feat/a ──────► main
         \── feat/b ──► main

• One eternal branch (main), short-lived feature branches
• Feature branches merge to main via PR
• Deploy from main immediately after merge
• Best for: SaaS, continuous deployment, small teams

2. Git Flow (structured — releases + hotfixes)

main ────► v1.0 ───► v1.1 ───► ...
  \                  ▲
   develop ──► feat ─┘
       \──► release/1.0 ──► main + develop

• main = production releases only
• develop = integration branch
• feature/ → develop, release/ → main + develop, hotfix/ → main + develop
• Best for: versioned releases, mobile apps, libraries

3. Trunk-Based Development (fastest — CI/CD)

main ──► short-lived ──► main (commit, not PR)

• All developers commit to main directly (or very short-lived branches, <1 day)
• Feature flags for incomplete work
• Best for: mature CI/CD, high-trust teams, microservices

4. GitLab Flow (environments)

main ──► pre/prod ──► production

• Environment branches (staging, production) as deploy targets
• Feature branches → main → downstream
• Best for: multiple deployment environments

Choosing a Model

Setup

# Protect main branch (replace with your remote)
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --input - <<< '{
    "required_status_checks": {"strict": true, "contexts": ["continuous-integration"]},
    "enforce_admins": true,
    "required_pull_request_reviews": {"required_approving_review_count": 1}
  }'

# Set default branch (if using Git Flow)
git checkout -b develop main
git push origin develop
gh api repos/:owner/:repo --method PATCH \
  --field default_branch=develop

Naming Conventions

feature/JIRA-123-short-description   # Feature branches
bugfix/JIRA-456-whats-broken         # Bug fixes
release/v1.2.3                       # Release branches (Git Flow)
hotfix/v1.2.4                        # Critical production fixes
chore/update-deps                    # Maintenance

Pitfalls

• Mixing models: Don't combine Git Flow's develop with trunk-based commits — pick one
• Stale long-lived branches: Set branch lifecycle (auto-delete after merge)
• Protection rules without CI: Branch protection is useless without required status checks
• Release branch drift: Cherry-pick critical fixes back to develop/main

Verification

git branch -a --merged main    # Check for stale branches
git log --oneline --graph --all --decorate  # Visualize branching health