DEV Community

Amaresh Pelleti
Amaresh Pelleti

Posted on Originally published at devtoolhub.com

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

Originally published on DevToolHub.

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. Below are the commands and what happened.

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

Open the pull request and close the issue

gh pr create --title "Increase test timeout" --body "Raises the timeout to 30s. Closes #2" --draft
Enter fullscreen mode Exit fullscreen mode

The Closes #2 closing keyword closed the issue when the PR merged. Issues and pull requests share one number sequence: my issue was #2, so the next PR was #3.

Merge and delete the branch

gh pr merge 1 --squash --delete-branch
Enter fullscreen mode Exit fullscreen mode

main gained one commit, Increase test timeout (#1), and the remote and local branches were deleted. Deleted branches come back from the PR's head commit:

S=$(gh api repos/OWNER/REPO/pulls/1 -q .head.sha)
gh api -X POST repos/OWNER/REPO/git/refs -f ref=refs/heads/increase-test-timeout -f sha=$S
Enter fullscreen mode Exit fullscreen mode

Enforce it with a ruleset

With a pull_request rule requiring one approval on the default branch:

  • A direct push to main was rejected: Changes must be made through a pull request.
  • gh pr merge without approval: the base branch policy prohibits the merge
  • Approving my own PR: Review Can not approve your own pull request
  • gh pr merge --admin also failed, because the ruleset had no bypass actor

On a private repo, creating the ruleset returned HTTP 403: Upgrade to GitHub Pro or make this repository public to enable this feature.

What I did not test

One repo, one user. Not tested: required status checks, auto-merge, merge queues, team reviewers, CODEOWNERS, the web UI, GitHub Desktop, or Enterprise.

Full write-up with the ruleset JSON and FAQ: GitHub Flow: 6 Steps, Tested With the gh CLI and Rulesets.

Top comments (0)