| name | apply-github-flow |
| description | Use when a team deploys continuously from a single mainline — to keep `main` always deployable, use short-lived feature branches, and ship via PR without release branches or long-lived parallel branches. |
| source | Chacon "GitHub Flow" (scottchacon.com, 2011); GitHub "Understanding the GitHub flow" (docs.github.com); Forsgren, Humble & Kim "Accelerate" (IT Revolution, 2018) |
| tags | ["github-flow","branching","continuous-deployment","feature-branches","pull-requests","ci-cd","git-workflow"] |
Apply GitHub Flow
Keep main always deployable. Every change lives in a short-lived feature branch, ships through a PR with passing CI, and deploys immediately on merge.
Why This Is Best Practice
Adopted by: GitHub itself (the originating team), Netlify, Vercel, Shopify, and the majority of SaaS teams practising continuous delivery; Scott Chacon (GitHub co-founder) published the canonical description in 2011; Forsgren, Humble & Kim's "Accelerate" (2018) empirically validates the single-mainline approach as a differentiator of elite-performing engineering teams
Impact: Forsgren et al. "Accelerate" (2018): elite DevOps performers — who deploy from a single trunk/mainline — achieve 46× more frequent deployments and 440× faster lead time than low performers; GitHub internal data shows GitHub Flow teams average < 24h feature branch lifetime vs > 5 days for GitFlow teams, directly reducing merge conflict frequency; eliminating the develop/main divergence that GitFlow requires removes the most common source of "integration hell" in multi-week sprints
Why best: GitFlow solves a problem (coordinating infrequent scheduled releases) that continuous deployment teams do not have; applying GitFlow to a team that deploys daily adds branch management overhead — develop, release/*, hotfix/* — with no benefit; GitHub Flow is the minimal viable branching strategy for teams where main can always be in a releasable state; the alternative (feature flags without branching) requires more infrastructure; GitHub Flow is the sweet spot between no-branch chaos and GitFlow ceremony
Sources: Chacon "GitHub Flow" (scottchacon.com, 2011); GitHub Docs "GitHub flow" (docs.github.com); Forsgren, Humble & Kim "Accelerate" (IT Revolution, 2018, Ch. 4); Humble & Farley "Continuous Delivery" (Addison-Wesley, 2010)
Steps
1. Verify the precondition: main is always deployable
GitHub Flow only works if the team commits to one rule: main must be in a deployable state at all times.
This requires:
- CI pipeline that runs on every push to
main
- Merge protection rule: PRs to
main require passing CI before merge
- A deployment pipeline that can deploy
main at any time (ideally automatically on merge)
If main is not currently always deployable, fix that before adopting GitHub Flow — the workflow is built on this invariant. A broken main in GitHub Flow is worse than a broken develop in GitFlow because main is production.
2. Create a feature branch from main
git checkout main
git pull origin main
git checkout -b <descriptive-branch-name>
Branch naming conventions:
feature/add-user-avatar-upload
fix/auth-token-expiry-off-by-one
chore/upgrade-node-18
docs/update-api-authentication-guide
- Use a prefix that signals type (
feature/, fix/, chore/, docs/)
- Use lowercase kebab-case
- Include a ticket/issue reference if your team tracks them:
feature/PROJ-42-user-avatar
- No date suffixes, no initials — branch names describe the change, not the author or time
Branch lifetime target: < 1–2 days. Branches that live longer accumulate drift from main and increase merge conflict probability. If a branch will take > 2 days, break the work into smaller increments or use a feature flag to ship the partial implementation safely.
3. Push early, open a draft PR
Push the branch to origin and open a draft PR before the work is complete:
git push -u origin <branch-name>
gh pr create --draft --title "feat: add user avatar upload" --body "Work in progress..."
Why open early:
- Signals work-in-progress to the team — prevents duplicate work
- CI runs immediately on push — catches issues early rather than at review time
- Reviewers can begin async review before the author marks it ready
Mark the PR ready for review only when all CI checks pass and the work is complete.
4. Develop with frequent small commits
Commit early, commit often. Push to the branch after each logical unit of work:
git add -p
git commit -m "feat: add S3 presigned URL generation for avatar upload"
git push
Frequent pushes to the feature branch:
- Keep CI feedback loop short (push → CI result in minutes, not after a full day's work)
- Preserve a granular history if bisect is needed later
- Allow reviewers to follow progress asynchronously
5. Merge only when CI passes
Before marking the PR ready for review, verify:
✅ All CI checks pass (tests, lint, type check, security scan)
✅ No merge conflicts with main (rebase if needed)
✅ Self-review: read your own diff as a reviewer would
✅ PR description explains WHY, not just what (link to issue/ticket)
Handle conflicts by rebasing, not merging:
git fetch origin
git rebase origin/main
git push --force-with-lease
Use --force-with-lease (not --force) — it fails if someone else pushed to the branch since your last fetch, preventing accidental overwrite.
6. Deploy immediately on merge to main
After PR approval and merge:
The deployment should be automatic — triggered by merge to main. If deployment requires a manual step, it will be skipped under pressure, breaking the "always deployable" invariant.
If immediate auto-deploy is not possible: use feature flags to merge safely before the feature is activated. Merge to main (invisible behind flag) → deploy → enable flag when ready.
7. Delete the branch after merge
git push origin --delete <branch-name>
git branch -d <branch-name>
GitHub can be configured to delete branches automatically on PR merge (repository Settings → General → "Automatically delete head branches"). Enable this.
Stale branches pollute the branch list, confuse git branch -a output, and occasionally get accidentally re-opened. Delete them.
Rules
main is always deployable — never merge a broken PR; never commit directly to main- Branch from
main, target main — no develop branch; no release branches
- Branch lifetime < 2 days — longer means the work needs to be broken down or feature-flagged
- Merge only when CI passes — no exceptions for "just a small fix"
- Deploy on merge — if deployment is manual, the workflow breaks under pressure
- Delete merged branches — enables automatic deletion via GitHub settings
Common Mistakes
- Long-lived feature branches: a branch that lives 2+ weeks accumulates so much drift from
main that merge becomes a multi-hour project; break large features into vertical slices or hide behind feature flags
- Committing directly to
main: bypasses CI and PR review; enable branch protection rules to make this physically impossible: Settings → Branches → Add rule → "Require pull request reviews" + "Require status checks"
- Not deploying on merge: teams that merge to
main but deploy weekly have GitHub Flow's simplicity with none of its benefit; the workflow only pays off when merge = deploy
- Draft PRs left open indefinitely: draft PRs are for work-in-progress, not for parking incomplete features; a draft PR open > 3 days is a work breakdown problem
- Using GitHub Flow for multiple concurrent release versions: if you need to maintain v1.x and v2.x simultaneously, GitHub Flow has no mechanism for this; use GitFlow or a long-lived release branch strategy instead
When NOT to Use
- Teams with scheduled release cycles (quarterly, monthly, sprint-based deployment) and formal change approval gates — the "deploy on merge" step conflicts with change management; use
apply-gitflow instead
- Teams maintaining multiple concurrent supported versions (mobile SDK at v2 and v3 simultaneously) — GitHub Flow has one mainline; parallel version maintenance requires release branches; use
apply-gitflow
- Teams without any CI — GitHub Flow's safety relies on CI catching regressions before merge; without CI, merging directly to
main is high-risk; establish CI first
