Team Workflows and Protecting the Main Branch
Learn the feature branch workflow, see a rule that refuses direct pushes to main, and learn what GitHub branch protection can require.
In this lesson you will
- Describe the feature branch workflow
- Explain what branch protection can require
- Read a simple server rule
- Write down a workflow for your team
About 30 minutes
Everyone can push, so who keeps main safe?
The garden club now has six volunteers with write access, and one afternoon someone pushes a half finished change straight to main. The page everyone reads is broken for two days. Nobody did anything wrong on purpose. The project simply had no rule, and a rule that depends on people remembering is a weak rule. A team workflow is an agreement about how changes reach the shared branch. The best agreements are partly enforced by the tools.
The feature branch workflow
The most common workflow is easy to say. main always holds work that is ready. Every change starts on its own short branch. The branch is pushed, reviewed through a pull request, and merged. Then the branch is deleted. You have been practising all of this since lesson 7. The only new idea is making the tools hold the line.
On GitHub, the rule is a setting called branch protection, or its newer alternative, rulesets. At the time of writing, a protected branch can require a pull request with a number of approving reviews, require checks to pass, require conversations to be resolved, and require a straight history without merge commits. By default the rules may not apply to repository administrators, depending on settings. Availability depends on the plan and on whether the repository is public, so check GitHub’s current pages.
GitHub’s settings cannot be reached from here, so the session below builds the same idea with plain Git. A shared repository gets a small script, called a hook, that runs on the server whenever someone pushes. This hook refuses any push to main that is not a merge commit. A merge commit is exactly what a pull request merge produces, so the rule is a fair imitation of “changes arrive by pull request”.
$ mkdir team
$ cd team
$ git init --bare shared.git
Initialized empty Git repository in /home/nia/team/shared.git/
$ printf '#!/bin/sh\nwhile read old new ref; do\n [ "$ref" = "refs/heads/main" ] || continue\n git rev-parse -q --verify "$old^{commit}" >/dev/null || continue\n n=$(git rev-list --parents -n 1 "$new" | wc -w)\n if [ "$n" -ne 3 ]; then\n echo "main only takes merge commits: open a pull request"\n exit 1\n fi\ndone\n' > shared.git/hooks/pre-receive
$ chmod +x shared.git/hooks/pre-receive
$ cat shared.git/hooks/pre-receive
#!/bin/sh
while read old new ref; do
[ "$ref" = "refs/heads/main" ] || continue
git rev-parse -q --verify "$old^{commit}" >/dev/null || continue
n=$(git rev-list --parents -n 1 "$new" | wc -w)
if [ "$n" -ne 3 ]; then
echo "main only takes merge commits: open a pull request"
exit 1
fi
done
Read the script slowly, because it shows what a rule is made of. It reads the old and new positions of each updated branch. It skips any branch that is not main, and skips a brand new main, because there is no old position to protect. Otherwise it counts the parents of the new commit. A merge commit has two parents, so the count of words is three, with the commit itself. Anything else is refused with a message.
The rule in action
$ git clone shared.git nia-copy
Cloning into 'nia-copy'...
warning: You appear to have cloned an empty repository.
done.
$ cd nia-copy
$ printf "Beans: row 1\n" > plan.txt
$ git add plan.txt
$ git commit -m "Add planting plan"
[main (root-commit) 73f8f33] Add planting plan
1 file changed, 1 insertion(+)
create mode 100644 plan.txt
$ git push -u origin main
To /home/nia/team/shared.git
* [new branch] main -> main
branch 'main' set up to track 'origin/main'.
$ echo "Carrots: row 2" >> plan.txt
$ git commit -am "Add carrots"
[main ed860e1] Add carrots
1 file changed, 1 insertion(+)
$ git push
remote: main only takes merge commits: open a pull request
To /home/nia/team/shared.git
! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to '/home/nia/team/shared.git'
$ git reset --hard origin/main
HEAD is now at 73f8f33 Add planting plan
$ git switch -c add-carrots
Switched to a new branch 'add-carrots'
$ echo "Carrots: row 2" >> plan.txt
$ git commit -am "Add carrots"
[add-carrots 80a0dc0] Add carrots
1 file changed, 1 insertion(+)
$ git push -u origin add-carrots
To /home/nia/team/shared.git
* [new branch] add-carrots -> add-carrots
branch 'add-carrots' set up to track 'origin/add-carrots'.
The first push works because it creates main. The second, a plain commit straight on main, is refused: the server prints the message from the hook and says the update was declined. Nia undoes her local commit with a hard reset, as lesson 5 taught, and does the right thing instead. She makes a branch, commits, and pushes the branch, which the rule does not touch.
$ git switch main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
$ git merge --no-ff add-carrots -m "Merge pull request: add carrots"
Merge made by the 'ort' strategy.
plan.txt | 1 +
1 file changed, 1 insertion(+)
$ git push
To /home/nia/team/shared.git
73f8f33..2ca3811 main -> main
$ git log --oneline --graph
* 2ca3811 Merge pull request: add carrots
|\
| * 80a0dc0 Add carrots
|/
* 73f8f33 Add planting plan
Then the change is merged into main with a merge commit, and the push is accepted. The graph shows the shape every protected workflow produces: the main line, with short branches joining it through merge commits.
What a good workflow also needs
- Small pull requests. They are reviewed faster and break less.
- Clear branch names that say what they are for, such as fix-3-tuesday.
- An agreement on the merge method, as in lesson 13.
- Named reviewers. GitHub supports a file that lists who must review which parts, called a code owners file. Check its help pages for the current format.
- A way to move fast in emergencies, with a note afterwards. Rules that cannot bend get ignored.
Some teams prefer very short branches that merge into main many times a day. This is often called trunk based development. It needs strong checks and small steps, but it avoids long branches that drift. The right choice depends on the size of the team and the risk of the project.
Making a rule so strict that people work around it, for example by sharing one account. A rule people respect is better than one they dodge.
The server script is a teaching stand-in for GitHub’s branch protection and is not how GitHub implements it. GitHub’s settings, names, plan limits and administrator exceptions change over time, so confirm them on its help pages.
Practice for this lesson
Check what you learned
Five quick questions. Pick an answer and you will see straight away whether it is right and why.
What is the feature branch workflow?
- Everyone commits straight to main
- Only one person may use Git
- Branches are never deleted
- Each change starts on its own branch and reaches main through review and merge
Nia’s change went through add-carrots.
What did the hook refuse?
- Any push to a branch
- A plain commit pushed straight to main
- The first push
- A merge commit
The server said the update was declined.
How many parents does a merge commit have?
- One
- Zero
- Three
- Two
The hook counted the parents to recognise a merge.
What can branch protection on GitHub require?
- Reviews, passing checks and resolved conversations, depending on settings
- Nothing at all
- Only a README
- A paid password
The exact options and plan limits change, so check current help pages.
Why do rules that cannot bend often get ignored?
- Git forbids rules
- Rules slow computers
- People work around them when real emergencies arrive
- Nobody reads rules
A good workflow includes a way to move fast, with a note afterwards.
Summary
- A workflow is an agreement on how changes reach main, ideally enforced by tools.
- On GitHub, branch protection or rulesets can require reviews, checks and a tidy history.
- A merge commit has two parents, which is how the stand-in rule recognised a merge.
- Good rules are small, clear and allow a way to handle emergencies.
Questions
Is branch protection available for free?
At the time of writing it is available for public repositories on the free plan and for more repositories on paid plans. Plans change, so check GitHub's current pages.
Do the rules apply to administrators?
It depends on the settings. Some rules can be set to include administrators. Check the current options.
What is trunk based development?
A style where everyone merges small changes into the main branch very often. It needs strong automated checks and small steps.
