GitHub Flow: 6 Steps, Tested With the gh CLI and Rulesets

GitHub flow: a short-lived branch goes through a pull request and merges into main

GitHub flow: branch, commit, pull request, review, squash merge, delete the branch

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 with push declined due to repository rule violations and Changes must be made through a pull request.
  • gh pr merge on a PR with no approval: the base branch policy prohibits the merge. The PR showed mergeStateStatus: BLOCKED and reviewDecision: 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

Leave a Reply