The previous lesson ended with the note Vincent Driessen himself added to his article ten years later: for continuous web development, Git Flow is too much. This lesson explains what lies on the other side of that recommendation.

GitHub Flow is the minimalist model. It grew out of GitHub's internal practice and was formalised by Scott Chacon in 2011 in an article titled, without ceremony, "GitHub Flow", with a premise that was almost a provocation at the time: for many projects, a single long-lived branch is enough.

And it is worth understanding where that claim comes from. It is not simplifying for the sake of convenience. It is that Git Flow solves a problem — coordinating several released versions and a stabilisation phase — that many projects do not have. If your application is deployed from a server you control, if there is only ever one version in production at a time, and if you can release a fix twenty minutes after writing it, then develop, release/* and hotfix/* are solving nothing for you: they are charging you complexity in exchange for nothing.

In task-manager the two realities coexist. The company sells the installable version — and for that one they keep Git Flow, as we saw — but it also runs a cloud version, app.example.com, which they deploy themselves several times a week. For that second line, the team has decided to try GitHub Flow.

1. The idea in one sentence
2. The six rules
3. The complete cycle, with a graph
4. The constraint that holds everything up: main always deployable
5. What it demands in return
6. The merge method: merge commit, squash or rebase
7. Versions without release branches: tags on main
8. Protected branches: the mechanism that enforces the flow
9. When GitHub Flow fits
10. Its limits

There is a single long-lived branch, main, which is always in a deployable state. Everything else is short branches that come off main, get reviewed in a pull request and go back into main.

That is the entire model. There is no develop, no release/*, no hotfix/*. An urgent fix does not need a class of branch of its own because every branch is equally fast: it comes off main, gets reviewed, goes in and gets deployed. The distinction between "urgent fix" and "ordinary feature" disappears from the branching model and becomes, at most, a label on the ticket.

The comparison of topologies, without yet going into the full comparison we shall make in lesson 07-05:

And a consequence you notice from day one: it is impossible to forget the second merge, because it does not exist.

Chacon stated them like this. We reproduce them with what each one means in practice.

Not "it compiles". Not "it's nearly there". Deployable: if somebody deploys main to production right now, the result is correct. It is the rule the other five depend on, and we devote the whole of section 4 to it.

Always from main, always up to date. The name should explain the work to somebody who only sees the list of branches: follow the conventions of lesson 03-06 — feature/, fix/, docs/ — and avoid tests, temp or anas-branch.

Not once at the end: often. Three reasons, and all three are practical:

• Backup. If Bruno's laptop dies this afternoon, the work is on the server.
• Visibility. The rest of the team sees what is being worked on and does not duplicate effort.
• CI runs on every push (lesson 07-06). A failure found after ten minutes costs minutes; the same failure found three days later costs hours of rebuilding the context.

At any time, including the first day and the first commit. This rule baffles a lot of people: why open a PR for something unfinished?

Because the PR is not just a request to merge: it is where the conversation lives (lesson 07-01). Opening it early lets you ask for an opinion on the approach before investing three days, leave a record of what you are on, have CI test it, and let somebody tell you "Carla already did that somewhere else" before it is too late. That is what draft PRs are for.

Nothing goes into main without another person having looked at it (lesson 07-02). And without CI being green. These two requirements do not rely on goodwill: they are imposed technically with protected branches (section 8).

Merging into main and deploying are, ideally, the same act. The shorter the gap between the two, the better: if something goes wrong, you know exactly which change caused it, because only one has gone in.

A frequent variant in practice inverts the order: deploy the branch first and merge afterwards, once you have checked that it works in production. It is what GitHub does internally. It has the advantage that main never comes to contain anything broken, and the cost of needing infrastructure to deploy arbitrary branches. The mechanics of that deployment — environments, promotion, rollback — are the subject of lesson 10-05; here we stay with the part that concerns Git.

Compare it mentally with the graph in the previous lesson. There is no twin track here, no bridges between permanent branches, no stabilisation phase. A straight line with short branches hanging off it, and a deployment at every meeting point.

Ana's complete cycle, from start to finish:

One detail that matters more than it seems: the branch should last days, not weeks. If a GitHub Flow branch has been open for three weeks, the model has stopped working: you have rebuilt a long-lived branch under another name, and with it all the late-integration problems we criticised in the previous lesson. Lesson 07-05 will take this idea to its extreme.

Since main moves on while you work, and the branch is short, this is usually trivial:

Many teams configure the platform to require the branch to be up to date with main before it can be merged. It is an additional guarantee (CI will have tested the real combination) in exchange for having to update the branch whenever somebody gets in ahead of you. In teams with a lot of activity, that requirement creates a continuous race that is solved with a merge queue, which we shall see in lesson 07-06.

This is the section to really understand. The rest is procedure.

GitHub Flow looks simpler than Git Flow because it has fewer branches. But it is not free: it has swapped process complexity for a very strong constraint. Git Flow let you have develop broken for three days because stabilisation happened afterwards, on the release branch. GitHub Flow removes that safety net. There is no release branch. There is no subsequent QA phase. main is what gets deployed, full stop.

Think about what that implies:

• If main is broken, nobody can deploy. Neither the person who broke it nor anybody else. The whole team is blocked.
• If main is broken and it goes unnoticed, it gets deployed broken.
• And if main is broken, you cannot release an urgent fix either, because the fix would go out accompanied by whatever is broken.

Hence this model's most important informal rule: fixing main is the team's top priority, ahead of any feature. If main's CI goes red, whatever is being done stops until it is green again. Many teams apply an automatic revert policy: if main breaks and is not fixed within ten minutes, the guilty commit is reverted (git revert, lesson 05-06) and it gets investigated calmly on a branch. Revert first, understand later.

And another, less obvious consequence: the size of each deployment drops a great deal. If you deploy after every PR, each deployment contains one change. When something fails in production, the list of suspects has one item on it. Compare that with deploying a quarterly release with a hundred and twenty changes inside it: when something goes wrong, the archaeology begins. That reduction of risk per deployment is the model's real benefit, and it is what compensates for the constraint.

The constraint of rule 1 does not hold itself up. It demands three things, and if any of them is missing the model does not work: it degrades into "we push to main and pray".

This is the indispensable condition. Nobody can manually guarantee that main is deployable after every merge: you need a test suite that runs on every push and every PR (lesson 07-06).

And reliable is the key word. A suite that fails randomly one run in ten — what is called a flaky test — is worse than having no tests, because it teaches the team to ignore failures. The moment somebody says "run it again, it fails sometimes", the signal is dead and with it the guarantee that main is deployable.

We already quantified this in lesson 07-02: above a few hundred lines, review stops finding defects. In a model where review is the last barrier before production, that is risk, plain and simple.

Besides, a small PR gets reviewed the same day, merged the same day and deployed the same day. A thousand-line PR waits three days for somebody to have a gap, and in those three days it accumulates conflicts.

Branches of days, not weeks. It is the same idea as the previous demand seen from the angle of time rather than size: the longer a branch lives apart, the more it diverges, the more conflicts it generates and the longer the value takes to reach the user.

And if the work is genuinely large and cannot be broken up into small PRs? There is an answer — feature flags and branch by abstraction — and it is one of the central topics of lesson 07-05.

It is worth saying plainly, because it is the most common failure: a team reads that GitHub Flow is "simpler", removes develop and the release branches, and does not invest in automated tests. The result is not simplicity: it is that main is broken half the time and nobody dares to deploy. They have taken away Git Flow's safety net without building GitHub Flow's.

GitHub Flow is not Git Flow minus branches. It is Git Flow minus branches plus automation.

When closing a pull request you have to decide how those commits go into main. The platforms offer three options, and the choice determines what the project's history will look like for ever.

You already know all of this from modules 3 and 5: here we just look at what each option produces in the context of a PR.

Equivalent to git merge --no-ff (lesson 03-03). All the branch's commits are preserved and a merge commit is added.

Equivalent to the merge --squash of lesson 03-04. All the branch's commits are condensed into a single one on main, and the original branch disappears from the history.

Equivalent to a git rebase (lesson 05-01) followed by a fast-forward. The commits are rewritten on top of the tip of main, in a straight line and with no merge commit.

Practical observations on each one:

Squash is the most popular in teams using GitHub Flow, and for a very specific reason: it absorbs untidy commits. The branch's wip, fixed and now it works disappear and what is left in main is one clean line per integrated change. The price is real: you lose the detail of how the change was built, and in a large PR the resulting commit is an enormous block that git blame cannot break down. It is the right choice if the PRs are small; if they are large, squashing makes things worse.

The ordinary merge preserves everything, but it only adds value if the branch's commits were well built (lesson 05-02). If they were not, it pollutes main with permanent noise. Its great advantage is git log --first-parent main: a perfect summary of the project, one line per PR.

Rebase and merge gives a linear history with no merge commits, but it completely loses the grouping: there is no way to know which commits arrived together, and reverting "that PR" means reverting N commits by hand. It is the least used of the three.

And now the important point:

Choose one and apply it always. A repository where every PR is merged with a different method has a history that cannot be read consistently: --first-parent means nothing, bisect gives uneven results and nobody knows what to expect. The specific decision and its consequences for the history are the content of lesson 08-02: Keeping a Clean History, where we shall deal with history policy in full. Here it is enough to know that the decision exists, that it is taken once, and that the platforms let you disable the methods you do not want so that nobody presses the wrong button.

With no release/*, how do you know what was released and when? With tags on main (lesson 05-05).

The idea is simple: every deployment to production gets tagged. The tag does not change what is in the repository; it adds a stable name to a commit so that you can come back to it.

Since there is no stabilisation phase, many teams that deploy frequently abandon SemVer for the application — there is not much point deciding whether a deployment is a minor or a patch when there are four a day — and use date-and-sequence tags:

What is worth keeping is SemVer for libraries, and ui-components is exactly that case: other projects depend on it and need to know whether a version breaks compatibility.

Tags are also the natural mechanism for three everyday things:

And a third piece the platforms offer: deployment environments, a record of which commit is live in each environment. It is useful, but managing it is the subject of lesson 10-05; from Git's point of view, what there is is a tag and a reference.

This is where GitHub Flow shines, because it needs no special mechanism. The urgent fix follows exactly the same path as any other change:

Twenty minutes from start to finish. In Git Flow that same thing required a class of branch of its own, two merges and a patch tag. Deployment speed makes hotfix/* unnecessary: when deploying costs minutes, every fix is a hotfix.

Everything above is agreement. And as we saw in lesson 06-01 when talking about client-side hooks, agreements that depend on human discipline fail on a Friday at seven in the evening.

The piece that turns GitHub Flow into something real is the protected branch: a set of rules the server applies to a specific branch and that nobody can bypass from their laptop.

The usual protections on main:

When Ana tries to push directly to a protected main, the rejection comes from the server:

Look at the last line in brackets: protected branch hook declined. That is literally a server hook rejecting the update of the reference. It is the pre-receive/update family that lesson 06-01 announced, and it is also the answer to the question left open there: this cannot be bypassed with --no-verify, because --no-verify only affects the hooks that run on your machine. Here the server decides.

We shall develop it in full in lesson 07-06, including how a status check becomes a mandatory requirement. For now, the idea to hold on to: GitHub Flow with protected branches is a process; GitHub Flow without them is a recommendation.

A note on organisational design: almost every platform allows certain roles to bypass the protections. It is tempting to leave that door open "just in case", but it is worth thinking twice. The exception always gets used at the worst possible moment — a production incident, in a hurry and short of sleep — which is exactly when the checks are most needed.

Typical examples: internal web applications, SaaS, APIs deployed by the team itself, static sites, internal tools. And the specific case in this course: app.example.com, the cloud version of task-manager.

It is also, by a distance, the most used model today, and it is the one you will find by default in most open source projects: an outside contributor makes a fork (lesson 07-01), opens a branch, sends a PR against main and that is that. No develop, no release branches, no more protocol than necessary.

Being honest about the limitations is what allows you to choose well.

This is the fundamental limit. If you have clients on 1.4 and on 2.0 and both need security fixes, a single long-lived branch cannot represent two simultaneous production states. There is no way to fix 1.4 from main, which is already on 2.0.

The practical solution is a hybrid: GitHub Flow for day-to-day development plus maintenance branches created from the tags whenever they are needed:

It is exactly what the task-manager team does for the installable version. And note the nuance: it is not "switching to Git Flow", it is adding the specific missing piece when it is needed, which is always better than adopting a whole model up front.

Without reliable tests and without fast CI, the model degrades quickly. A team without that foundation is safer with Git Flow, where the release branch gives a margin for manual stabilisation. It is an uncomfortable but true conclusion: the simpler model demands more maturity, not less.

A database migration, a rewrite of the interface, an architectural change. They do not fit into a three-day branch and they cannot be integrated half-finished into a main that has to be deployable. GitHub Flow offers no answer; it has to be brought in from outside, and that answer — feature flags and branch by abstraction — is one of the topics of the next lesson.

If every release requires a quality manager's sign-off, formal documentation or an authorised deployment window, the "merge and deploy" of rule 6 is not applicable as it stands. It can be adapted (integrate continuously, deploy in windows), but then main accumulates undeployed changes and part of the benefit is lost.

Mistake 1: adopting GitHub Flow without automated tests. Git Flow's net is taken away without building your own. main ends up broken half the time.

Mistake 2: three-week branches. That is a long-lived branch under another name, with all the late-integration problems the model was meant to avoid.

Mistake 3: leaving main broken and carrying on working. It blocks the whole team, urgent fixes included. Fixing main is the absolute priority; if it takes more than a few minutes, revert.

Mistake 4: not protecting main. Without protected branches the model is a recommendation that somebody will bypass. With them it is a process.

Mistake 5: mixing merge methods. Some PRs with squash, others with a merge commit, others with rebase. The resulting history cannot be read consistently.

Mistake 6: squashing enormous PRs. Squash works with small PRs. Squashing a thousand lines produces a commit that git blame cannot break down and that nobody will be able to understand a year from now.

Mistake 7: not tagging the deployments. Without tags there is no way to know what was in production last Tuesday, nor to go back to it to debug.

Mistake 8: creating the branch without updating main first. git switch main && git pull first, always. Starting from a week-old main generates avoidable conflicts.

Mistake 9: living with unstable tests. A test that fails one time in ten teaches the team to ignore the red, and with that the guarantee of rule 1 dies. Fix it or remove it, but do not ignore it.

Tip 1: PRs of under 200 lines. It is what has the biggest impact on the speed and quality of the flow (lesson 07-02).

Tip 2: open the PR on day one, as a draft. CI starts testing sooner and somebody can correct your course in time.

Tip 3: delete the branch when merging. Turn it on in the platform and use git fetch --prune locally. A repository with two hundred dead branches is unusable.

Tip 4: disable in the platform the merge methods you do not use. It is more reliable than trusting that nobody presses the wrong button.

Tip 5: measure the lifetime of your branches. If the average is over a week, you are not doing GitHub Flow, whatever you call it.

Tip 6: add maintenance branches only when a real client needs them. Do not adopt the whole of Git Flow for a problem you may never have.

On a new repository with index.html, app.js and styles.css:

1. Create main with three initial commits and tag it as v2.3.0.
2. Simulate three complete cycles: a branch from main, two commits, back to main with --no-ff, delete the branch and add a deployment tag.
3. Use branch names following the project's conventions: one feature/, one fix/ and one docs/.
4. Show the graph and check that it resembles the one in section 3.
5. Run git log --oneline --first-parent main and explain what information it gives you.

1. Create a branch feature/export with four commits, two of them clearly noise (wip, fixed).
2. Make three copies of the repository at /tmp/method-merge, /tmp/method-squash and /tmp/method-rebase.
3. In each copy, integrate the branch with the corresponding method (merge --no-ff, merge --squash + commit, rebase + merge --ff-only).
4. Compare across the three: git log --oneline, git log --oneline --first-parent and the number of commits in main.
5. In each copy, try to revert the whole feature with a single command. In which is it possible?
6. Run git blame app.js in all three and comment on the differences.

1. Starting from the exercise 1 repository, simulate a production bug: create fix/task-loss from main, fix it, merge it and tag the deployment.
2. Count how many commands were needed from the initial switch to the tag.
3. Compare that number with the equivalent hotfix/* procedure in Git Flow (lesson 07-03, section 7). How many steps have you saved, and which Git Flow step simply does not exist here?
4. Now the other side: simulate that a client is still on v2.3.0 and needs that same fix without receiving anything else. Create support/2.3 from the tag, bring the fix over with cherry-pick and tag v2.3.1.
5. Explain why step 4 is not part of GitHub Flow and what that tells you about when the model falls short.

Solution 1:

--first-parent gives one line per merged PR: it is the project's readable summary. That is the main benefit of merging with an ordinary merge commit.

Solution 2:

With a merge commit and with squash, one command is enough. With rebase you have to revert each commit, because nothing indicates that they were a set.

In squash, every line of the feature points at the same commit and the same message: the information about which part was done at which step has been lost.

Solution 3:

Six commands. In Git Flow: create from main, fix, bump the patch version, merge into main, tag, merge into develop as well, delete in two places. The step that does not exist here is the second merge, and it is precisely the one most often forgotten and the most expensive when it is.

GitHub Flow is the dominant model today, and its simplicity is real but conditional. The essentials:

• A single long-lived branch, main, always deployable. Everything else is short branches that come off main, get reviewed in a PR and go back into main. There is no develop, no release/*, no hotfix/*, and no double integrations to forget.
• The six rules: main deployable; descriptive branches off main; push constantly; open the PR at any time; merge only after review; deploy immediately afterwards.
• "main always deployable" is the constraint that holds the model up, and it is not free: if main breaks, the whole team is blocked, urgent fixes included. Fixing main is the absolute priority; if it drags on, revert.
• In exchange for removing branches, the model demands reliable automated tests, small PRs and frequent integration. GitHub Flow is not Git Flow minus branches: it is Git Flow minus branches plus automation. Without that foundation, it degrades.
• The merge method — merge commit, squash or rebase — determines the history for ever: squash absorbs untidy commits and is optimal for bisect, the merge commit preserves the detail and enables --first-parent, rebase loses the grouping. Choose one and apply it always; the complete policy is in lesson 08-02.
• With no release branches, tags on main record what was deployed and when: SemVer for libraries such as ui-components, date and sequence for applications with several deployments a day.
• Urgent fixes need no mechanism of their own: when deploying costs minutes, every fix is a hotfix.
• Protected branches turn the agreement into a process: forbid direct pushing, require approvals and green checks. And that protected branch hook declined is a server hook, precisely what --no-verify cannot touch.
• It fits web and SaaS with a single version in production, frequent deployment and good tests. Its limit is maintaining old versions: for that you need to add support branches from the tags.

There is one question this model leaves open. GitHub Flow asks for short branches, but how short? And what do you do with work that does not fit into three days? There is a school of thought that answers by taking the idea to its extreme: integrate into the trunk at least once a day, every person, always, and decouple deployment from release with feature flags so that this is possible even with half-finished work. That is the approach of lesson 07-05: Trunk Based Development, where we shall also finally compare the three flows in a single table and build a decision tree for choosing between them.