Git Branching and Workflow

Principles and mainline

Whatever style you pick, agent-written conventions should answer: who may push mainline directly, integration frequency, who resolves conflicts and when, and default rollback / cherry-pick policy.

• Naming: whether feat/, fix/, chore/ prefixes are mandatory, and whether ticket IDs (e.g. PROJ-1024) must appear in branch names.
• Sync: how long-lived branches stay current with main to avoid “big bang” merges and hidden integration risk.
• Permissions: who can bypass protection, and whether emergency hotfixes need dual review or retroactive approval.

Trunk-based vs GitFlow: when to use which

They are not mutually exclusive labels—think integration cadence and release responsibility. The SKILL should state which you resemble and allowed exceptions (e.g. temporary freeze during a release window).

• Closer to trunk-based development: small, frequent merges to main; short-lived branches or feature flags hide incomplete work; CI keeps main green; fits fast delivery with mature automation from small to large teams.
• Closer to GitFlow (or a trimmed variant): long-running develop integration line, explicit release branches, parallel versions—fits fixed release cycles and strict separation between “next integration” and “production fixes”, at the cost of more branch/merge overhead; document who merges and who deletes branches.

Branch topology and merge cadence

The sketch below is classic GitFlow simplified; if you have trimmed it (e.g. dropped develop, only main + release/*), redraw the equivalent topology in the SKILL and mark deprecated edges.

  main (production / release merges only)
    ●──────────────●──────────────●  tag: v1.2.0 …
    ↑ \            ↑              ↑
    │  \  hotfix   │  release/*   │
    │   *──*───────┘   fixes only │
    │                              │
 develop (daily integration)        │
    ●───●───●───●───●──────────────┘
     \   \   \   \
      \   \   \   └── feat/fix branches (short-lived, merge back to develop)
       \   \   \
        └───┴── optional: long topic branches (document sync policy)

For trunk-based workflows, switch to a single hub: feature branches open PRs directly against main, rebase or merge before landing, and document minimum sync frequency with main (daily / weekly).

  [ Feature branch ready to merge ]
            │
       ┌────┴────┐
       ▼         ▼
  Prefer linear history   Prefer merge context
  (often with             (keep merge commits
   squash)                 and branch topology)
       │         │
       ▼         ▼
  rebase then fast-forward    merge --no-ff (or platform equivalent)
       │         │
       └────┬────┘
            ▼
    [ Pass CI + review + branch protection ]
            ▼
         Land on mainline

# Branch naming conventions and creation examples

# Feature branches
git checkout -b feat/user-auth-oauth        # New feature
git checkout -b feat/JIRA-123-checkout-v2   # With ticket reference

# Bug fix branches
git checkout -b fix/cart-total-rounding     # Bug fix
git checkout -b fix/JIRA-456-null-pointer   # With ticket reference

# Hotfix (production emergency, branch from main/tag)
git checkout -b hotfix/payment-timeout main

# Release preparation
git checkout -b release/v1.4.0

# Maintenance (docs, chores)
git checkout -b docs/api-reference-update
git checkout -b chore/upgrade-node-20

# Merge strategies comparison:
# Squash merge (clean history, one commit per PR)
git merge --squash feat/user-auth-oauth
git commit -m "feat(auth): add OAuth2 login support"

# Rebase + Fast-forward (linear history, preserves commits)
git rebase main feat/user-auth-oauth
git checkout main && git merge --ff-only feat/user-auth-oauth

# Merge commit (preserves branch topology)
git merge --no-ff feat/user-auth-oauth -m "Merge: feat(auth) OAuth2 login"

Protection rules and permissions

List rules by severity so generated checklists map cleanly to GitHub/GitLab (and similar) settings.

• Mainline: no force-push, PR/MR required, required checks passing, up-to-date before merge if enabled.
• Review: minimum approvers, CODEOWNERS or path rules, whether self-approval is forbidden.
• Compliance: signed commits, no direct pushes to sensitive branches, audit log retention.

# GitHub branch protection configuration (gh CLI)

# Protect main branch: require PRs, status checks, and signed commits
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"contexts":["ci/tests","ci/lint"]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
  --field restrictions=null \
  --field allow_force_pushes=false \
  --field allow_deletions=false

# CODEOWNERS file example (.github/CODEOWNERS)
# Syntax: <path-pattern>  <@team or @user>

# Global owners (fallback for all files)
*                           @org/platform-team

# Frontend: require frontend team review
/src/frontend/              @org/frontend-team
/src/components/            @org/frontend-team

# Backend services
/src/services/auth/         @org/auth-team
/src/services/payment/      @org/payments-team

# Infrastructure: require SRE review for infra changes
/terraform/                 @org/sre-team
/k8s/                       @org/sre-team
/.github/workflows/         @org/sre-team

# Sensitive configs: require security team sign-off
/src/config/security.ts     @org/security-team

Releases, tags, and hotfixes

If you use release branches and tags (SemVer, prerelease -rc, LTS maintenance), document them next to the release pipeline: who creates tags, whether tags trigger deploy, and whether rollback is revert vs retag.

Spell out hotfix flow: branch from main or release/x.y, merge back into which lines, and whether dual upstream merges are mandatory to prevent drift.

# Release tagging (SemVer)

# Create and push a release tag
git tag -a v1.4.0 -m "Release v1.4.0: OAuth login, cart fixes"
git push origin v1.4.0

# Create a release candidate
git tag -a v1.4.0-rc.1 -m "Release candidate 1 for v1.4.0"
git push origin v1.4.0-rc.1

# List all tags with creation date
git tag -l --sort=-version:refname | head -10

# Hotfix flow (production emergency)
git checkout -b hotfix/v1.3.1 v1.3.0     # Branch from release tag
# ... make fix ...
git commit -m "fix(payment): handle timeout edge case"
git tag -a v1.3.1 -m "Hotfix v1.3.1: payment timeout"
git push origin hotfix/v1.3.1 v1.3.1
# Merge back to main and release branch
git checkout main && git cherry-pick <fix-commit-sha>
git checkout release/v1.3 && git cherry-pick <fix-commit-sha>

SKILL outline (for agents generating team docs)

---
name: git-branch-workflow
description: Branch strategy, naming conventions, protection rules, and merge discipline
version: 2.0
---
# Strategy selection
- Trunk-Based Development: for teams with strong CI/CD and feature flags
- GitFlow: for products with formal versioned releases (mobile apps, libraries)
- Hybrid: trunk for application code, release branches for deployable artifacts

# Branch naming
- feat/<ticket>-short-description
- fix/<ticket>-short-description
- hotfix/v<version> (branch from release tag)
- release/v<major.minor>
- chore/ | docs/ | refactor/ for non-feature work

# Protection rules (main / master)
- No force push; require PRs with at least 1 approval
- Required status checks: CI tests + lint must pass
- CODEOWNERS for domain-specific review requirements
- Signed commits enforced for audit trail

# Merge strategy
- Squash merge: clean linear history, one commit per PR (recommended for feature branches)
- Rebase + Fast-forward: linear history with full commit granularity
- Merge commit: preserves branch topology (use for release branch merges)

# Release and hotfix
- Tag releases: git tag -a v1.4.0 -m "Release message"
- Hotfix: branch from release tag, fix, tag patch, cherry-pick back to main

Branch name self-check

Defaults match the examples above: prefix feat, fix, chore, docs, hotfix, or release, then / and a slug without spaces (letters, digits, hyphen, underscore, dot, multi-segment paths OK). Update this page’s script when you change the regex in your SKILL.