Skip to main content

Git Branching Strategy

tip

This page is current and ready for use.

Table of Contents​

Development Workflow Setup​

Branch Strategy​

main → develop → feature/123-feature-name
               → bugfix/123-bug-description

Environment Branches​

  • main - Production code
  • develop - Development integration branch
  • qc - Quality control testing
  • uat - User acceptance testing
  • staging - Pre-production verification

Development Process​

Create Issue → Create Branch → Development → Tests →
Code Review → QA → UAT → Staging → Production

Branch Types & Naming​

Feature Branches​

  • Format: feature/123-description
  • Purpose: New feature development
  • Create: When starting new feature development
  • Delete: After successful merge to develop and release to Production
  • Typical lifespan: 1-4 weeks

Bugfix Branches​

  • Format: bugfix/123-description
  • Purpose: Regular fixes during development
  • Create: When bug found in release testing
  • Delete: After merge to both release/v1.2.3 and develop
  • Typical lifespan: 1-7 days

Hotfix Branches​

  • Format: hotfix/123-description
  • Purpose: Urgent production fixes
  • Create: When critical production bug found
  • Delete: After merge to main, develop, and applicable release branches
  • Typical lifespan: 1-3 days

Release Branches​

  • Format: release/v1.2.3
  • Create: When starting release cycle
  • Delete: 1-2 months after successful production deployment
  • Keep temporarily for any potential hotfix backports
  • Typical lifespan: 2-3 months

Environment Branches​

  • Branches: develop, qc, uat, staging, main
  • These are permanent branches
  • Never delete

Testing Environment Strategy​

Individual Feature Testing Environment​

Each feature branch should have:

  • Its own testing URL (e.g., feature-123.dev.oxagry.com)
  • Isolated database
  • CI/CD pipeline that automatically deploys to this environment
  • Automated test suite (unit, integration)

Testing Flow​

feature/123 → Individual Test Environment → Code Review → develop
             (feature-123.dev.oxagry.com)

Environment Structure​

Feature Environments:    feature-*.dev.oxagry.com    (Dynamic, temporary)
Development:            develop.oxagry.com           (Stable integration)
QC:                     qc.oxagry.com               (Quality testing)
UAT:                    uat.oxagry.com              (User testing)
Staging:                staging.oxagry.com          (Pre-production)
Production:             oxagry.com                  (Live)

This ensures:

  • Features can be tested in isolation
  • QA can test features independently
  • No interference between features
  • Clean environments for proper testing

Development Workflow​

Starting New Feature​

# Update develop first
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/123-feature-name

During Development​

# Regular sync with develop
git checkout feature/123-feature-name
git fetch origin
git merge origin/develop

# Or using rebase
git rebase origin/develop

Completing Feature​

# Final update from develop
git merge origin/develop

# Push to remote
git push origin feature/123-feature-name

Integration Process​

Code Review & Merge​

  1. Create Merge Request to develop
  2. Assign reviewers
  3. Pass code review
  4. Run automated tests
  5. Resolve conflicts if any
  6. Merge to develop

Merge Request Requirements​

  • All tests passing
  • Code review approval
  • No merge conflicts
  • Documentation updated
  • Meets coding standards

Release Management​

Creating Release​

# From develop
git checkout develop
git checkout -b release/v1.2.3

# Testing flow
git push origin release/v1.2.3
# Deploy to QC → UAT → Staging

Finalizing Release​

# After successful testing
git checkout main
git merge release/v1.2.3
git tag v1.2.3

# Back-merge to develop
git checkout develop
git merge release/v1.2.3

Best Practices​

Commit Guidelines​

  • Use clear, descriptive commit messages
  • Include issue number in commits
  • Make atomic commits
  • Keep features isolated where possible

Branch Management​

  • Regular develop integration
  • Delete feature branches after merge
  • Keep branches up to date
  • Resolve conflicts early

Documentation​

# Feature Branch Documentation Template
Feature: [Name]
Issue: #[Number]
Dependencies:
- [List dependencies]
Testing:
- [Test cases]

Branch Lifecycle & Cleanup​

Cleanup Policy​

  • Regular cleanup of merged feature/bugfix branches (monthly)
  • Archive release branches instead of deleting if needed for audit
  • Automate cleanup using GitLab's settings where possible

Branch Protection​

  • Implement strict protection rules for permanent branches
  • Configure merge request approvals
  • Set up CI/CD requirements
  • Define role-based access

Branch Protection Rules​

Develop Branch​

  • Require merge request
  • Minimum 1 approval
  • CI pipeline must pass
  • No direct pushes

Main Branch​

  • Protected branch
  • Only release managers can merge
  • Requires release process
  • CI/CD must pass

Environment Branches​

  • Protected branches
  • Deployment automated
  • Specific access roles
  • Regular cleanup

Tools & Integration​

Protected Branches​

  • main (only release managers can merge)
  • develop (requires code review)
  • qc, uat, staging (restricted push)

GitLab Configuration​

# Branch protection
protected_branches:
  main:
    allowed_to_push: ["release-managers"]
    allowed_to_merge: ["release-managers"]
  develop:
    allowed_to_push: ["developers"]
    allowed_to_merge: ["developers"]
    required_approvals: 1

CI/CD Pipeline Stages​

stages:
  - lint
  - build
  - test
  - deploy

Merge Request Template​

## Description
[Feature/Fix description]

## Dependencies
- [ ] List dependencies

## Testing
- [ ] Unit Tests
- [ ] Integration Tests

## Review Checklist
- [ ] Code follows style guide
- [ ] Tests added/updated
- [ ] Documentation updated

Notes​

  • This strategy prioritizes integration over isolation
  • Suitable for early-stage development
  • Facilitates team collaboration
  • Enables continuous integration
  • Provides clear release path

Support​

For questions or clarifications about this Git strategy, please contact the technical leads.