GitHub Flow: Simple Branching for Continuous Delivery

If you’ve ever looked at Git Flow with its five different branch types, release schedules, and complicated lifecycle diagrams and thought “there has to be a simpler way” — you’re not alone. GitHub Flow was born exactly because Git Flow solves problems that most teams don’t actually have. GitHub Flow strips away the complexity: there’s one rule that governs everything — every line of code starts from main and every line of code merges back to main.

This works because GitHub built this model around a single assumption: if your tests pass and your code is reviewed, you’re ready to deploy. No staging branches, no version tags, no release candidates. When your feature branch merges to main, it goes to production. Some of the fastest-moving teams in the industry run on this philosophy, and this post explains why it works, when it breaks down, and how to make it work for your team.

Introduction

There are a lot of ”## when to use / when not to use” sections in this file — they read like filler content from an AI generator. The core idea behind GitHub Flow is simple: if your tests pass and your code is reviewed, you’re ready to deploy. No staging branches, no version tags, no release candidates. When your feature branch merges to main, it goes to production. Some of the fastest-moving teams in the industry run on this philosophy, and it works — provided you have the CI/CD infrastructure and feature flag culture to back it up. This guide covers when this model shines, where it breaks down, and how to implement it without shooting yourself in the foot.

When to Use / When Not to Use

Use GitHub Flow When

• Continuous deployment — You deploy to production multiple times per day or week
• Web applications and SaaS — No packaging, signing, or app store approval process
• Small to medium teams — Where communication overhead of complex branching outweighs benefits
• Feature flag culture — You control feature rollout with flags, not branch timing
• Automated testing — Your CI pipeline catches regressions before they reach main

Do Not Use GitHub Flow When

• Scheduled releases — You ship on a calendar cadence with QA gates
• Multiple supported versions — You need to patch v1.x while developing v2.x
• Regulated environments — You need formal change management and release documentation
• No CI/CD pipeline — Without automated testing, every merge to main is a gamble
• Mobile or desktop apps — Where each release requires a build and distribution process

Core Concepts

GitHub Flow has exactly three concepts:

That’s it. No release branches. No develop branch. No version branches. The simplicity is the entire point.

graph LR
    A[main - Always Deployable] --> B[feature/new-ui]
    A --> C[feature/api-v2]
    A --> D[feature/bugfix]
    B -->|PR + CI| A
    C -->|PR + CI| A
    D -->|PR + CI| A
    A --> E[Deploy to Production]

Architecture and Flow Diagram

The complete GitHub Flow lifecycle from branch creation through production deployment:

graph TD
    A[main - Production] -->|create branch| B[feature/branch]
    B -->|commit| B
    B -->|push| C[Remote Feature Branch]
    C -->|open PR| D[Pull Request]
    D -->|code review| E[Review Feedback]
    E -->|update| C
    D -->|CI passes| F[Approved]
    F -->|merge| A
    A -->|auto deploy| G[Production]

Step-by-Step Guide

1. Create a Feature Branch

Always branch from the latest main:

# Ensure you have the latest main
git checkout main
git pull origin main

# Create and switch to your feature branch
git checkout -b feature/add-user-profile

Branch naming conventions matter for traceability:

# Good: descriptive with ticket reference
feature/PROJ-123-add-user-profile
feature/add-dark-mode
bugfix/fix-login-timeout

# Bad: vague or personal
feature/work-in-progress
johns-branch
temp-fix

2. Commit and Push Frequently

Small, focused commits make code review easier and bisect more effective:

# Make changes
git add src/components/UserProfile.tsx
git commit -m "feat: add user profile component skeleton"

git add src/styles/profile.css
git commit -m "feat: style user profile card"

# Push to remote
git push -u origin feature/add-user-profile

3. Open a Pull Request

The pull request is the heart of GitHub Flow. It’s where code review, automated testing, and team discussion converge:

# Using GitHub CLI
gh pr create \
  --base main \
  --head feature/add-user-profile \
  --title "feat: add user profile page" \
  --body "## Summary
Adds user profile page with avatar, bio, and settings link.

## Testing

- Manual: /profile endpoint renders correctly
- Unit: UserProfile component tests pass
- E2E: Profile navigation flow verified

## Screenshots

[Attach screenshots if UI changes]"

4. Review and Iterate

Code review is mandatory in GitHub Flow — it’s the only quality gate before main:

• At least one approved review required
• All CI checks must pass (tests, linting, type checking)
• Address review comments with additional commits to the same branch
• The PR updates automatically with each push

5. Merge and Deploy

Once approved and green:

# Merge via CLI or UI
gh pr merge feature/add-user-profile --squash --delete-branch

# The merge triggers deployment
# CI/CD pipeline detects main branch update and deploys

Most teams use squash merges to keep main history clean, but some prefer merge commits for topology preservation.

Production Failure Scenarios

Deployment Verification Checklist

After each merge to main, verify the deployment succeeded:

• CI pipeline completed with all green checks
• Deployment logs show successful rollout with correct commit SHA
• Health endpoint responds with 200 OK
• Error rate in monitoring is within normal baseline (< 1% increase)
• Key user journeys pass smoke tests (login, core feature, checkout)
• No new Sentry/alerting errors in the last 5 minutes
• Database migrations (if any) completed successfully
• Feature flags for the new feature are in the intended state
• Rollback procedure is documented and tested if this is a high-risk deploy

Trade-off Analysis

Implementation Snippets

Branch Protection Rules

# GitHub repository settings (via API or UI):
# Required pull request reviews: 1
# Dismiss stale reviews: enabled
# Require status checks: build, test, lint
# Require branches to be up to date: enabled
# Include administrators: enabled
# Restrict pushes that create matching files: enabled

GitHub Actions — CI Pipeline

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --coverage

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        run: ./scripts/deploy.sh
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

Feature Flag Integration

// src/features/userProfile.ts
import { isFeatureEnabled } from '@/utils/featureFlags';

export function UserProfilePage() {
  if (!isFeatureEnabled('user-profile')) {
    return null; // Or redirect to a fallback
  }

  return <UserProfile />;
}

// Feature flag evaluation
// src/utils/featureFlags.ts
export function isFeatureEnabled(flag: string): boolean {
  const flags = process.env.FEATURE_FLAGS || '{}';
  return JSON.parse(flags)[flag] === true;
}

Quick Revert Script

#!/bin/bash
# scripts/revert-last-merge.sh
# Revert the last merge commit on main

git checkout main
git pull origin main

# Find the last merge commit
LAST_MERGE=$(git log --oneline --merges -1 --format="%H")

if [ -z "$LAST_MERGE" ]; then
  echo "No merge commits found on main"
  exit 1
fi

echo "Reverting merge: $LAST_MERGE"
git revert -m 1 "$LAST_MERGE"
git push origin main

echo "Revert pushed. CI will redeploy the previous version."

Observability Checklist

• Logs: Log every PR merge event with author, PR number, and commit SHA
• Metrics: Track PR cycle time (open to merge), deployment frequency, and mean time to recovery
• Traces: Correlate each deployment with the PR that triggered it and any subsequent incidents
• Alerts: Alert on deployment failure rate > 5%, PRs open longer than 3 days, or main branch CI failures
• Dashboards: Display deployment frequency, lead time for changes, change failure rate, and MTTR (DORA metrics)

GitHub Flow vs Trunk-Based Development

GitHub Flow and trunk-based development are close relatives — same core idea, different tolerances for how long branches can live. GitHub Flow works with branches that stick around for days or weeks. Trunk-based development expects branches to be opened and closed within hours, with feature flags hiding incomplete work.

The practical difference comes down to infrastructure. GitHub Flow tolerates longer-lived branches because most teams don’t have the feature flag systems needed to merge incomplete code continuously. Trunk-based development requires that infrastructure as a baseline.

If you’re moving from GitHub Flow to trunk-based, you need:

• Feature flag system (LaunchDarkly, Unleash, Flagsmith, etc.)
• Canary deployment support in CI/CD
• A culture of merging incomplete features behind flags
• Rollback procedures that don’t require new deployments

Security and Compliance Notes

• Branch protection: Required reviews and status checks prevent unauthorized merges to main
• Signed commits: Require GPG-signed commits for cryptographic authorship verification
• CODEOWNERS: Use CODEOWNERS file to require specific team reviews for sensitive directories
• Secrets scanning: Enable GitHub secret scanning to prevent credential leaks in PRs
• Audit log: GitHub’s audit log tracks all repository events including branch protection changes
• Compliance gap: GitHub Flow lacks formal release artifacts — supplement with deployment logs and change tickets if required by your compliance framework

Common Pitfalls / Anti-Patterns

1. The Staging Branch — Adding a staging branch turns GitHub Flow into a half-baked Git Flow. Either commit to continuous deployment or use a different model.
2. Skipping Code Review — Merging your own PRs without review defeats the only quality gate. Enforce branch protection rules.
3. Massive PRs — Pull requests with 50+ files are impossible to review effectively. Break features into smaller, reviewable chunks.
4. Ignoring CI Failures — Allowing merges with failing checks means main is not always deployable. Make CI mandatory.
5. No Feature Flags — Without feature flags, every merged feature is immediately visible to users. This couples deployment to release.
6. Long-Lived Branches — Feature branches that exist for weeks defeat the purpose. Merge small, merge often.
7. Direct Commits to main — Bypassing PRs for “emergency fixes” creates inconsistency. Use the same process for everything.

Quick Recap Checklist

• main branch is always deployable and represents production
• Every change starts as a feature branch from main
• Pull requests require at least one review before merge
• CI pipeline runs tests, linting, and type checks on every PR
• Merged PRs trigger automatic deployment to production
• Branch protection rules prevent direct pushes to main
• Feature flags control feature visibility independent of deployment
• PRs are kept small and focused for effective code review
• Failed deployments trigger automatic rollback
• DORA metrics are tracked and reviewed regularly

Interview Questions

# Teams
/src/api/ @api-team
/src/ui/ @frontend-team
/docs/ @docs-team
Individuals
*.sql @senior-dba
/security/** @security-team

Further Reading

• GitHub Flow documentation — Official GitHub guide
• GitHub Flow vs Git Flow — Atlassian’s comparison
• Feature Flags best practices — LaunchDarkly’s guide
• DORA Metrics — Four key metrics for software delivery
• Trunk-Based Development — Related approach that GitHub Flow approximates

Conclusion

GitHub Flow strips branching to its essence — main branch, short-lived feature branches, and PRs. Its simplicity is its strength: every merge deploys, every deploy is fast, and there’s no ceremony between code and production.