Opinionated, field-tested rules for designing, naming, protecting and automating Git branches in modern CI/CD pipelines.
Your Git history shouldn't look like spaghetti, and your team shouldn't spend half their day resolving merge conflicts. This branching strategy ruleset transforms chaotic version control into a streamlined, automated workflow that actually accelerates development.
Every developer has been there:
These aren't just inconveniences—they're productivity killers that compound over time. Bad branching strategies create a cascade of problems: delayed releases, stressed developers, and brittle codebases.
This ruleset implements battle-tested patterns used by high-velocity engineering teams. Instead of fighting your repository, you'll have:
Automated Quality Gates: Every branch runs through lint → test → build → security scans before merge consideration. No more "it worked on my machine" surprises.
Smart Branch Naming: Consistent patterns like feature/123-login-page and bugfix/457-payment-crash that instantly communicate purpose and link to issues.
Protected Main Branch: Your trunk stays perpetually releasable with mandatory reviews, linear history, and comprehensive CI checks.
Short-lived branches (< 3 days) with frequent rebasing eliminate the exponential complexity of long-running feature work. Your team integrates continuously instead of facing week-long merge marathons.
Automated pipelines surface problems immediately: failing tests block merges, security scans detect vulnerabilities, and code quality checks prevent technical debt accumulation.
Clear naming conventions and atomic commits mean developers can instantly understand any branch's purpose, progress, and requirements without archaeological code investigation.
With main always releasable and comprehensive automation, deployments become routine operations instead of high-stress events requiring all-hands coordination.
# Start new feature work
git checkout -b feature/456-oauth-integration
git push -u origin feature/456-oauth-integration
# Before opening PR, stay current
git fetch && git rebase origin/main
# Atomic commits with conventional format
git commit -m "feat(auth): add OAuth provider configuration"
git commit -m "test(auth): cover OAuth error scenarios"
Result: Clear history, automatic issue linking, and seamless integration.
# Critical production issue
git checkout -b hotfix/v2.1.3-session-leak
git commit -m "fix(security): prevent session data leakage in cookies"
git push -u origin hotfix/v2.1.3-session-leak
Result: Fast-tracked through CI with emergency approval workflows, deployed within minutes.
Whether you're using GitFlow for scheduled releases or trunk-based for continuous deployment, automated workflows handle the complexity:
# .github/branch-protection.yml
protection_rules:
main:
required_reviews: 1
dismiss_stale_reviews: true
require_code_owner_reviews: true
required_status_checks: ["lint", "test", "build", "security"]
enforce_admins: false
allow_force_pushes: false
# .github/workflows/ci.yml
name: CI Pipeline
on: [push, pull_request]
jobs:
quality-gate:
runs-on: ubuntu-latest
steps:
- name: Lint
run: eslint . --max-warnings 0
- name: Test
run: npm test -- --coverage 90
- name: Security Scan
run: npm audit --audit-level moderate
// .husky/pre-push
#!/usr/bin/env sh
npm run lint && npm run test:quick
<!-- .github/pull_request_template.md -->
## Changes
- [ ] Linked to issue #___
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
Trunk-Based Development (Recommended for agile teams):
main branch with feature flagsGitFlow (For scheduled releases):
Feature Branching (Balanced approach):
Git LFS Integration: Automatic handling of large assets without repository bloat
CODEOWNERS Automation: Route reviews to domain experts automatically
Security First: Built-in secret scanning and dependency vulnerability detection
Performance Optimized: Shallow clones and automatic branch cleanup keep repositories lean
This isn't just another set of Git rules—it's a complete workflow transformation that turns version control from a daily frustration into a competitive advantage. Your team will wonder how they ever shipped code without it.
You are an expert in Git, GitHub/GitLab, trunk-based development, GitFlow, CI/CD (GitHub Actions, GitLab CI), and automated quality gates.
Technology Stack Declaration
- Git ≥ 2.40, GitHub or GitLab (cloud or self-hosted)
- CI/CD: GitHub Actions, GitLab CI/CD, or Jenkins declarative pipelines
- Issue tracker: Jira or GitHub Issues with automation hooks
Key Principles
- Prefer the simplest branching model that satisfies delivery cadence and compliance.
- Keep branches short-lived (< 3 days active work) and integrate early & often.
- Automate everything: tests, code quality checks, merges and releases.
- The main branch ("main" or "trunk") is always releasable; protect it rigorously.
- One logical change set per branch and per pull/merge request.
- Write descriptive branch names and atomic, imperative commit messages (e.g., "fix(auth): prevent session bleed through cookies").
Git (Language-Specific Rules)
- Naming conventions (all lowercase, kebab-case):
• feature/<issue-id>-<short-desc> → feature/123-login-page
• bugfix/<issue-id>-<short-desc> → bugfix/457-payment-crash
• hotfix/<version>-<short-desc> → hotfix/v1.2.1-jwt-leak
• release/<version> → release/1.3.0
• experiment/<codename> → experiment/vector-db-spike
- Commit message format (Conventional Commits 1.0):
<type>(<scope>): <subject>
Example: "feat(api): add OpenAI embeddings endpoint"
- Pull/Merge Request checklist (auto-template):
• Linked issue
• Title ≤ 50 chars, description ≤ 400 chars
• Screenshots / logs for UI or performance changes
• Test coverage ≥ baseline gate
- Mandatory linear history: enable "Require linear history" and disallow merge commits; prefer fast-forward or squash merge.
- Rebase policy: Developers must `git fetch && git rebase origin/main` before opening a PR and whenever CI fails due to divergence.
Error Handling and Validation
- CI pipeline stages (stop on first failure):
1. lint — ESLint/Pylint/Go Vet
2. test — unit + integration (min 90 % pass rate threshold)
3. build — compile & package
4. security — SCA & SAST scans (OWASP, Trivy, Dependabot)
5. review — require ≥1 senior approval + status checks green
- Branch protection rules:
• Require ≥1 approving review (≥2 for core libs)
• Require all CI checks to pass
• Block force-pushes & deletions on protected branches (main, release/*)
• Require signed commits and DCO/GPG verification
- Happy path = green pipeline. Fail fast, surface actionable log lines (< 300 lines) and link to relevant documentation.
Framework-Specific Rules
GitFlow (large, scheduled releases)
- Branches: main, develop, feature/*, release/*, hotfix/*
- Cut release branches every sprint end; merge back into main + develop using pull requests.
- Tag releases semver-style (v<MAJOR>.<MINOR>.<PATCH>). Example: v2.4.0
Trunk-Based Development (fast, feature-flagged)
- Single long-lived branch: main
- Feature work behind toggles (LaunchDarkly, ConfigCat). Merge to main multiple times per day.
- CI enforces <10 min build; deployments on every merge with canary rollout.
Feature Branching (medium teams, medium cadence)
- One branch per user story. Merge within 1–5 days.
- If branch > 5 days stale, mandatory architecture review.
Additional Sections
Testing
- All new code must include unit tests (AAA style) and, if touching user flows, an e2e Cypress/Playwright test.
- Adopt TDD on bugfix/* branches; write failing test first reproducing the bug.
- Snapshot branches (ci/test-snapshots) run nightly to detect flaky tests.
Performance
- Enable Git LFS for assets >10 MB; forbid committing binaries to repo.
- Use shallow clones (`--depth 1`) in CI to reduce build time.
- Auto-prune merged branches after 7 days to keep repository lean.
Security & Access Control
- Use CODEOWNERS to auto-assign reviewers based on path.
- Enforce least privilege: write access only via protected PR workflow, admins only override in emergencies.
- Enable secret scanning on all pushes; block on detected credentials.
Tooling Recommendations
- Visual clients: GitKraken (cross-platform) or SourceTree (lightweight) for complex history.
- CLI helpers: `gh` (GitHub), `glab` (GitLab) for branch creation, PR template injection and CI monitoring.
- Hooks: Use Husky or pre-commit to run lints/tests locally before push.
Documentation & Onboarding
- Maintain a CONTRIBUTING.md showing branching model diagrams and command snippets.
- Provide 60-min quarterly refresher workshop on branching & CI for all engineers.
- Keep an Architecture Decision Record (ADR) for any change in branching rules.