
GitHub flow is a branch-per-change workflow: you branch off main, push commits, open a pull request, get a review, merge, and delete the branch. GitHub’s docs list exactly those six steps and no others.
I ran all six in a throwaway repository with git 2.56.0 and gh 2.103.3, then added a ruleset to see what it blocks. The commands and outputs below are from that run, and the last section lists what I did not test. For how this compares with Gitflow and trunk-based development, see our Git workflows comparison.
What Are the Six Steps of GitHub Flow?
| Step | What you do | Command I ran |
|---|---|---|
| 1. Create a branch | Short, descriptive name | git switch -c increase-test-timeout |
| 2. Make changes | Small commits, push often | git push -u origin increase-test-timeout |
| 3. Open a pull request | Draft first if you want early feedback | gh pr create --draft |
| 4. Address review comments | Push more commits; the PR updates itself | git push |
| 5. Merge | After approval | gh pr merge --squash --delete-branch |
| 6. Delete the branch | The PR and history stay | included in step 5 |
GitHub Flow Steps 1 and 2: Branch and Commit
The docs suggest names like increase-test-timeout and add-code-of-conduct, and they ask for one isolated, complete change per commit so it can be reverted alone.
git switch -c increase-test-timeout
echo "timeout: 30" > config.yml
git add config.yml
git commit -m "increase test timeout"
git push -u origin increase-test-timeout
GitHub’s docs also say to use a separate branch for each set of unrelated changes. Mixing two fixes in one branch is what makes a pull request hard to review and hard to revert.
GitHub Flow Step 3: Open a Pull Request
gh pr create --title "Increase test timeout" --body "Raises the timeout to 30s. Closes #2" --draft
--draft opened the PR as a draft, and gh pr view --json isDraft,state returned {"isDraft":true,"state":"OPEN"}. When you are ready for review, gh pr ready 1 flips it.
The Closes #2 line is a closing keyword. I created issue #2 first, and it closed on its own when the PR merged. One gotcha: issues and pull requests share one number sequence. My first PR was #1, the issue was #2, and my next PR was #3, so gh pr merge 2 failed with “Could not resolve to a PullRequest with the number of 2”.
GitHub Flow Step 4: Address Review Comments
Reviewers comment on lines or on the whole PR. You answer by committing and pushing to the same branch:
echo "retries: 2" >> config.yml
git commit -am "add retries"
git push
No new PR is needed. The pull request picks up the commit, and any required checks run again.
GitHub Flow Steps 5 and 6: Merge and Delete the Branch
gh pr ready 1
gh pr merge 1 --squash --delete-branch
The PR state became MERGED, issue #2 became CLOSED, and main gained one commit titled Increase test timeout (#1). Both of my branch commits were squashed into it. --delete-branch removed the remote branch and the local one in the same command.
Deleting does not destroy the work. GitHub keeps the PR, and I brought the branch back from the PR’s head commit:
S=$(gh api repos/amareswer/dth-github-flow-test/pulls/1 -q .head.sha)
gh api -X POST repos/amareswer/dth-github-flow-test/git/refs -f ref=refs/heads/increase-test-timeout -f sha=$S
The call returned refs/heads/increase-test-timeout. If you forget --delete-branch, the repository setting that deletes branches on merge was false on my new repo, so branches pile up until you turn it on.
Can You Enforce GitHub Flow With a Ruleset?
Yes, and without one it is only a convention, because anyone with write access can push to main. I created a ruleset on the default branch that requires a pull request with one approval:
gh api -X POST repos/OWNER/REPO/rulesets --input ruleset.json
with this body:
{"name":"protect-main","target":"branch","enforcement":"active",
"conditions":{"ref_name":{"include":["~DEFAULT_BRANCH"],"exclude":[]}},
"rules":[{"type":"pull_request","parameters":{"required_approving_review_count":1,
"dismiss_stale_reviews_on_push":false,"require_code_owner_review":false,
"require_last_push_approval":false,"required_review_thread_resolution":false}}]}
Here is what happened next:
- Direct push to
main: rejected withpush declined due to repository rule violationsandChanges must be made through a pull request. gh pr mergeon a PR with no approval:the base branch policy prohibits the merge. The PR showedmergeStateStatus: BLOCKEDandreviewDecision: REVIEW_REQUIRED.- Approving my own PR:
Review Can not approve your own pull request. A solo maintainer cannot satisfy a one-approval rule alone. gh pr merge --admin: it also failed, because my ruleset had no bypass actor.
On a private repository, the same API calls returned HTTP 403: Upgrade to GitHub Pro or make this repository public to enable this feature. That was true for both rulesets and classic branch protection on my account, so I ran the enforcement test on a public repo. Check your own plan before you plan around it. GitHub’s rulesets page describes what a ruleset is but did not answer the plan question for me.
If you want required reviewers by file path, pair this with a CODEOWNERS file. For conflicts on a long-lived branch, see how to handle merge conflicts in Git.
When Does GitHub Flow Fit, and When Does It Not?
It fits teams that ship from main and merge small changes often. It has no release branch, so if you maintain several released versions at once, you will need more than these six steps. The current docs list no deploy step either; if you deploy, that belongs in your CI and your release tags, not in the flow itself.
What I Did Not Test
I used one repository, one user, and one account. I did not test required status checks, auto-merge, merge queues, team reviewers, CODEOWNERS enforcement, the web UI, GitHub Desktop, or GitHub Enterprise. The ruleset result comes from a single rule type, pull_request. Plan limits may differ for you.
Frequently Asked Questions
Q: Is GitHub flow the same as Git Flow?
A: No. GitHub flow has one long-lived branch, main, and short-lived feature branches. Gitflow adds develop, release and hotfix branches.
Q: Do I need a pull request for every change in GitHub flow?
A: Yes, that is the flow. A ruleset that requires pull requests is the way to make it a rule instead of a habit.
Q: Should I squash merge in GitHub flow?
A: It is a choice, not a requirement. Squash gave me one clean commit on main per pull request, at the cost of losing the individual commits from the branch history.
Q: Can I restore a branch after I delete it?
A: Yes. The pull request keeps its head commit, so you can recreate the branch from that SHA, as shown above.
Quick Summary:
– GitHub flow is six steps: branch, commit, pull request, review, merge, delete the branch
– gh pr create --draft and gh pr merge --squash --delete-branch cover most of it
– Closing keywords like Closes #2 close the issue on merge
– A ruleset blocked direct pushes to main and unapproved merges
– Rulesets returned 403 on a private repo on my account, so check your plan
GitHub flow works best when a ruleset makes the six steps the only way to change main.
Related guides
- GitHub Templates: PR, Issue & Discussion Best Practices
- Git Workflows: Git Flow vs GitHub Flow vs Trunk-Based Dev
- Git Pull vs Fetch: What Each Command Really Does
- Cherry-Picking a Commit in GitHub Desktop: CLI and GUI Guide
- Git vs Github for beginners
- GitHub Actions Incidents: What Actually Breaks in Production