Skip to content

Git Branching Strategy & Workflow

Overview

This document outlines our Git branching strategy and automated workflows. Our approach is designed to:

  1. Identify integration issues early
  2. Maintain clean release pipelines
  3. Provide clear visibility into the release process
  4. Minimize manual conflict resolution

Branch Structure

We use the following branch hierarchy:

master (production) ← staging (pre-release) ← dev (integration) ← feature branches
Branch Purpose Protection Merge Strategy
master Production code ✅ Merge via PR from release branches only
staging Pre-release testing ✅ Merge via PR from dev
dev Integration testing ✅ Auto-merge from feature branches
Feature branches Development ❌ Direct push

Synchronization Process

Our branches stay in sync through automated rebase operations:

  • Daily: staging rebases onto master to incorporate hotfixes
  • Daily: dev rebases onto staging to stay current with pending releases
  • This automated process creates PRs and alerts the team to conflicts that require manual resolution

Working with Feature Branches

Branch Naming

Use descriptive prefixes for your branch names:

  • feature/ - New features
  • fix/ - Bug fixes
  • chore/ - Maintenance tasks
  • docs/ - Documentation updates
  • refactor/ - Code refactoring
  • test/ - Test-related changes

Example: feature/add-user-authentication

Development Workflow

  1. Create a branch from dev:
git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name
  1. Make your changes on the feature branch:
# Make changes, then commit
git add .
git commit -m "feat: add your feature"
  1. Push your branch to GitHub:
git push -u origin feature/your-feature-name

  1. Automatic Integration:

  2. When you push to a feature branch, GitHub Actions will automatically:

    • Run the build and tests
    • Create a PR to merge your branch into dev

  3. Keep your branch up to date with dev: 

    git checkout dev
git pull origin dev
git checkout feature/your-feature-name
git rebase dev
git push --force-with-lease origin feature/your-feature-name

Promoting to Staging and Production

Dev to Staging (Feature Release)

When ready to prepare a release:

  1. Create a PR from dev to staging
  2. Complete thorough QA in the staging environment
  3. Get required approvals
  4. Merge the PR

Staging to Master (Production Release)

To promote to production:

  1. Navigate to GitHub Actions
  2. Run the "Release Promotion" workflow
  3. Input the release version (e.g., v1.2.3)
  4. Optionally add release notes
  5. The workflow will:
  6. Create a release branch from staging
  7. Create a PR to master
  8. Create a draft GitHub release
  9. After final approval, merge the PR to master
  10. Publish the GitHub release

Handling Conflicts

When the automatic rebase process detects conflicts:

  1. GitHub Actions will create a PR with conflicts marked
  2. Team members (usually leads) resolve conflicts manually
  3. Once resolved, the PR can be approved and merged

Emergency Hotfixes

For urgent production fixes:

  1. Create a branch from master named hotfix/description
  2. Make and test your changes
  3. Create a PR directly to master
  4. After approval and merge, create a PR to backport the fix to staging and dev

GitHub Actions Workflows

Branch Synchronization

The branch-sync.yml workflow runs:

  • Automatically every day at midnight UTC
  • Manually when triggered by a team member

It creates PRs for:

  • Rebasing staging onto master
  • Rebasing dev onto staging

Feature Branch Integration

The feature-to-dev.yml workflow runs:

  • Automatically on pushes to feature branches
  • Manually when triggered with a specified branch

It runs tests and creates PRs to merge feature branches into dev.

Release Promotion

The release-promotion.yml workflow:

  • Must be manually triggered
  • Allows specifying a version number and release notes
  • Creates a release branch from staging
  • Creates a PR to merge the release branch into master
  • Prepares a draft GitHub release

GitHub Repository Settings

Ensure the repository has these settings configured:

  1. Branch Protection for master:

  2. Require pull request reviews before merging

  3. Require status checks to pass

  4. Restrict who can push to matching branches

  5. Branch Protection for staging:

  6. Require pull request reviews before merging

  7. Require status checks to pass

  8. Branch Protection for dev:

  9. Require status checks to pass

  10. Required Status Checks:

  11. build-and-test job from CI workflow

Required GitHub Secrets

For these workflows to function properly, you need to set up these repository secrets:

  • BRANCH_SYNC_PAT: A GitHub Personal Access Token with repo permissions for branch synchronization
  • RELEASE_PAT: A GitHub Personal Access Token with repo permissions for release management

Need Help?

Contact the DevOps team for questions about this workflow or to report issues with the automated processes. No newline at end of file