Git Workflow Backgrounder

This backgrounder outlines common workflow approaches to provide context as we periodically evaluate our git workflow so that we can work collaboratively, transparently, and autonomously to produce high-quality product.

Topology Diagrams

• Permanent branches are outlined in red
• Ad-hoc branches are outliend in yellow
• The branch from which production depoloys has a pink fill
• Each topology has the addition of a “mirror” branch so we can compare apples-to-apples. The typical setup doesn’t have a mirror branch.

Business Requirements and Compliance Considerations

Our Git workflow must satisfy specific business, security, and compliance requirements while embodying our horizontal practices.

SOC2 Compliance Requirements

Our SOC2 certification imposes several requirements influencing our Git workflow:

1. Change Management: All changes to production code follow a documented approval process
2. Access Control: Clear separation between development and production environments
3. Audit Trail: Comprehensive logging of all code changes and deployments
4. Security Testing: Code undergoes security review before deployment
5. Documentation: Processes are well-documented and followed consistently
6. Data Handling Requirements:
   1. No PII in Development: We strictly avoid using personally identifiable information during development
   2. Production Data Testing: We use anonymized production data for testing and development
   3. Data Separation: Clear separation between development environments and production data

QA Process Requirements

1. Mirror Environment: We maintain a copy of production code available for QA and demo at all times. This enables us to see “production” behavior without violating our SOC2 requirement of keeping strict separation between develompent and production.
2. Release Candidate Staging: We conduct end-to-end testing prior to release, so we have to maintain a staging environment capable of supporting such testing.
3. PR / Ticketing: As part of our strategy for meeting our SOC2 audit trail requirement, every PR must be reviewed and the reason for the PR must be clear – usually by referencing the ticket.

Common Git Workflow Topologies

1. GitHub Flow

Production Branch: Main

Key Characteristics

• Single primary Main branch (trunk) containing production code
• Feature branches that branch from and merge back to Main via Pull Requests

Workflow Process

1. Create feature branches from Main
2. Complete work in these branches
3. Open Pull Requests for code review
4. Upon approval, features merge directly to Main
5. Deployment happens automatically from Main

Best For

• Small, high-trust teams
• Projects requiring continuous deployment
• Codebases where features can be completed quickly

Limitations

• Less formal control over releases
• Not ideal for managing multiple production versions
• Can be challenging for complex, longer-duration features

2. Trunk-Based Development

Production Branch: Main

Key Characteristics

• Single Main branch serving as both integration and production branch
• Very short-lived feature branches (explicitly limited to 1-2 days)
• Option for direct commits to trunk for minor changes

Workflow Process

1. Create short-lived branches from Main
2. Make small, focused changes and test them
3. Quickly merge back to Mainvia PR/Merge
4. Commit minor changes directly to Main
5. Deployment happens from Main, often using feature flags

Best For

• Teams practicing continuous integration
• Projects with frequent, small releases
• Experienced development teams with good testing practices
• Organizations with strong DevOps capabilities

Limitations

• Requires disciplined development practices
• Needs comprehensive automated testing
• Often requires feature flagging infrastructure
• May be challenging for junior developers

3. GitLab Flow [Our topology as of Dec 2025]

Production Branch: Production

Key Characteristics

• Main branch as the integration branch
• Pre-Production (staging) branch for testing
• Production branch containing deployed code
• Feature branches that merge to Main via Merge Requests

Workflow Process

1. Create feature branches from Main
2. Merge changes back to Main via MR
3. Merge Main to Pre-Production for testing
4. Release Pre-Production to Production when ready

Best For

• Teams needing explicit environment separation
• Projects requiring thorough testing before release
• Organizations with formal QA processes
• Multi-environment deployment pipelines

Limitations

• More complex branch management
• Possible drift between environments
• Requires more coordination between teams
• Slightly slower path to production than simpler models

4. GitFlow

Production Branch: Main/Master

Key Characteristics

• Two main long-lived branches: Main/Master (production) and Develop (integration)
• Feature branches that branch from and merge to Develop
• Release branches for preparing releases
• Hotfix branches for emergency production fixes

Workflow Process

1. We create feature branches from Develop
2. We merge features back to Develop via PR
3. When ready for release, we create a Release branch from Develop
4. We test and finalize Release branches
5. We merge Release branches to both Main (for deployment) and back to Develop
6. Hotfixes branch from Main and merge to both Main and Develop

Best For

• Larger teams working on complex projects
• Software with scheduled, versioned releases
• Projects requiring support for multiple versions
• Teams with formal release processes

Limitations

• Highest complexity of all workflows
• Can lead to long-lived branches and merge conflicts
• Slower release cycle
• More overhead for coordination

Further Reading

• Git Workflow Documentation
• GitFlow Original Article
• GitHub Flow Guide
• GitLab Flow Documentation
• Trunk-Based Development