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

1feature branch2open PR3review + CI4merge to main
every change rides the same small loop into main

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 mode

CI 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 pass

draft 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 first

code review

A human reading the diff before it lands — catching bugs, spreading knowledge, and leaving a paper trail.

approve or request changes

how it works

  1. 1
    Branch from main

    One idea per branch, named by type: feat/search-bar, fix/login-crash. The name should survive being read in three months.

  2. 2
    Open the PR early

    The moment the branch is pushed, open it — draft if unfinished. CI starts running and the team can see the direction.

  3. 3
    Push 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.

  4. 4
    Review like a teammate

    Ask questions and suggest instead of judging. Approve when it is good enough, not perfect — perfection is how PRs go stale.

  5. 5
    Merge 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

1$ git switch -c feat/search-bar
2$ git push -u origin feat/search-bar
3$ gh pr create --draft --fill
opens the PR from the command line
4# CI runs, humans comment
5$ gh pr checks --watch
watch CI without the browser tab
6$ gh pr merge --squash --delete-branch
one clean commit lands on main

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
VS

small PR

  • one idea, a focused diff
  • reviewed in minutes
  • merges before it goes stale
  • reverting is one clean commit
💡 tip

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

🎤 interview

Why do pull requests exist?watch ↗

🎤 interview

Review the code, not the personwatch ↗

🔧 useful

Branch names that explain themselveswatch ↗

🔧 useful

Open the PR earlywatch ↗

💎 deep

A form beats an empty wall of textwatch ↗

💎 deep

Track work without a meetingwatch ↗