GitHub Flow

What Is GitHub Flow?

GitHub Flow is a lightweight branching workflow published by GitHub in 2011. It is a simplification of GitFlow that removes release branches, hotfix branches, and develop branches. Every change goes through a feature branch, a pull request, code review, and merge to main. Production is deployed from main.

The workflow is simple enough to explain in one sentence: create a branch, make changes, open a PR, get reviewed, merge, deploy.

The Six Rules

GitHub Flow defines six rules that keep the workflow simple and reliable.

• main is always deployable.
• All work happens on feature branches — never directly on main.
• Feature branches are pushed to the remote regularly for backup and visibility.
• Pull requests are opened early — even before the work is done — to start conversation.
• Code review is required before merge.
• Merge only when the PR is approved, CI passes, and the branch is up to date.

The Workflow in Practice

# 1. Pull latest main
git switch main
git pull origin main

# 2. Create a feature branch
git switch -c feat/dark-mode

# 3. Make changes and commit
echo "Dark mode support" > src/theme.ts
git add src/theme.ts
git commit -m "feat: add dark mode theme support"

# 4. Push early and often
git push origin feat/dark-mode

# 5. Open a pull request (draft if work-in-progress)
gh pr create --draft --title "Add dark mode" --body "Closes #101"

# 6. Continue working, push more commits
echo "Dark mode toggle" > src/theme-toggle.ts
git add src/theme-toggle.ts
git commit -m "feat: add dark mode toggle component"
git push origin feat/dark-mode

# 7. Mark PR as ready for review
gh pr ready

# 8. After approval and CI passes, merge
gh pr merge --squash --delete-branch

# Create a branch and PR in one flow
git switch main && git pull
git switch -c fix/payment-timeout

# Fix the issue
sed -i 's/timeout = 5/timeout = 30/' src/api/client.ts
git add -A && git commit -m "fix: increase payment API timeout to 30s"
git push origin fix/payment-timeout

# Create PR with labels and assignees
gh pr create \
  --title "Fix payment timeout" \
  --body "Payments were timing out at 5s. Increased to 30s." \
  --label "bug,payment" \
  --assignee "@me"

# Check PR status
gh pr status

# Merge when ready
gh pr merge --squash --delete-branch

Pull Request Etiquette

Pull requests are the heart of GitHub Flow. Good PRs get reviewed faster and merged sooner.

GitHub Flow vs GitFlow

When to Use GitHub Flow

GitHub Flow is the default choice for most modern teams. It works when you deploy continuously, have automated tests, and your team can coordinate through pull requests.

• Web applications deployed to production continuously.
• API services with automated deployment pipelines.
• Teams smaller than 20 engineers.
• Projects with good test coverage and CI/CD.
• Open-source projects where contributors submit PRs.
• Any project where the main branch is always deployable.