GitHub Flow
How teams code together without crying.
▶ the lesson · narrated sketch video · tap for sound
the intro
GitHub flow is the lightweight team workflow: branch from main, open a pull request early, review and discuss, then merge when green. Pull requests are where code review, CI results, and team knowledge meet.
fun fact ✦
The pull request is the team’s immune system: nothing reaches main without passing through it.
the docs
the deep dive
the ideas behind the video — concepts, diagrams, a walkthrough and the traps to avoid
The whole workflow hangs on one rule: main is always shippable. All risk lives on short-lived branches, and the pull request is the toll booth back in — where a human reviews, CI runs, and the team remembers why the change happened. Teams that master this do not have fewer disagreements; they have them in writing, attached to code.
main stays shippable, branches carry the risk
key terms
pull request
A proposal to merge one branch into another, wrapped in a discussion thread, diffs, and CI results.
PR #142: add dark modeCI checks
Automated builds and tests that run on every push to the PR. Red means do not merge, no matter who asked.
lint + tests must passdraft PR
A pull request marked work-in-progress: CI runs and teammates can look, but review is not requested yet.
open it as a draft firstcode review
A human reading the diff before it lands — catching bugs, spreading knowledge, and leaving a paper trail.
approve or request changeshow it works
- 1Branch from main
One idea per branch, named by type: feat/search-bar, fix/login-crash. The name should survive being read in three months.
- 2Open the PR early
The moment the branch is pushed, open it — draft if unfinished. CI starts running and the team can see the direction.
- 3Push as you go
Every push updates the same PR. Do not squash your work into one heroic commit at the end; the review reads the final diff anyway.
- 4Review like a teammate
Ask questions and suggest instead of judging. Approve when it is good enough, not perfect — perfection is how PRs go stale.
- 5Merge and delete
Merge when green and approved, then delete the branch. The PR keeps the history; the branch was disposable.
the code, explained
the full loop without leaving the terminal
side by side
huge PR
- hundreds of lines across days
- reviewer fatigue, rubber stamps
- conflicts pile up while open
- one bug blocks the whole review
small PR
- one idea, a focused diff
- reviewed in minutes
- merges before it goes stale
- reverting is one clean commit
Open the pull request when the branch is born, not when the work is done. Early PRs get CI running, give reviewers a heads-up, and catch wrong directions while they are still cheap. Finishing is just the last push.
quick answers
Squash merge or merge commit?
Squash gives main one clean commit per PR; merge preserves your gritty work-in-progress history. Both are fine — the team just needs to pick one.
When do I update my branch with main?
Whenever main moves and before final review. Rebase your own branch or merge main in — on your private branch, either is safe.
Who should review my PR?
Whoever knows the code plus one fresh pair of eyes. CODEOWNERS can auto-assign the right first reviewers automatically.
quick hits about GitHub Flow
short answers · interviews, tips, trivia & hidden gems