apply-github-flow

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>
# Then open PR via GitHub UI or CLI:
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                      # stage hunks, not files
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
# resolve conflicts if any
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:

# GitHub merges PR → CI runs on main → deploy pipeline triggers automatically

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