GitHub Status Checks and Branch Protection Made Easy

Let the GitHub Knights of Branch Protection Guard Your Repo (📷 motoDanmoto)

Fortify Your Repo 🏰

GitHub provides a suite of options that allow you to determine specific criteria that must be met before a pull request can be merged into your repository. This article will outline how to configure branch protection rules that require pull requests to be reviewed, and status checks to ensure tests are run in a variety of environments. In less time than it takes to drink a cup of coffee, you can dramatically reduce the risk of rogue merges wreaking havoc on your code.

Protect Your Branch 🛡

The first step to guarding the kingdom is to add a branch protection rule. Adding a branch protection rule allows you to specify a list of criteria that must be met to merge a change into a protected branch. Specifying a list of criteria that must be met before a merge allows you to formalize and automate repetitive tasks that are necessary to ensure quality contributions to your repo. Branch protections are free for public repos, but require a Pro subscription to be added to private repos.

Add your first rule by clicking the Settings tab on your repos’ GitHub page and navigating to the Branches section. Take note of your Default Branch (usually main) and click Add Rule:

Enter main into the Branch name pattern input and hit Enter or click Save Changes:

Congrats! You have just defined main as a protected branch. In the next step, you will begin to define the criteria that must be met for changes to be merged into your protected branch.

Require Reviews 👀

When a review is required, someone with push access to your repo must give an open pull request their blessing before the pull request can be merged into a protected branch. Requiring a pull request review is a great way to reduce the number of bugs introduced as it ensures someone with experience working in your repo has inspected the change and asked questions where appropriate.

To require that pull requests be reviewed, click the checkbox next to Require a pull request before merging. Be sure to also click the checkbox next to Require approvals:

Awesome! Now when a pull request is opened the Merge button will be disabled until at least 1 contributor has reviewed and approved the changes. In the final step, we will add a status check to ensure that a specific action has run successfully to completion.

Run Tests 🦿

It’s important to run all the tests in your repository for any change proposed by contributors. Running tests for each pull request reduces the likelihood of regressions and other bugs being introduced to your code and ensures a higher degree of quality in the code merged to the protected branch. If you’re interested in learning more about testing, check out this article for a crash course on the basics of unit testing.

To configure a status check that leverages GitHub Actions to run your tests, create a .github/workflows/ci.yml file. The following gist contains a workflow that will run tests for a Node.js app:

If you’re not developing with Node.js you’ll have to modify ci.yml to work with your platform. Here are some links that outline how to run tests with GitHub Actions on other platforms: .NET, Python, Ruby, Swift, and Java.

To require a clean test run before a pull request can be merged, navigate back to your repo’s Settings page. Click the checkbox next to Require status checks to pass before merging. Search for ci in the Search for status checks in the last week for this repository input field and click the search result to enable the status check:

Nice! If you open a pull request you should notice that the merge button won’t turn green until the status checks are complete and the pull request has been reviewed:

Victory 👑

Thanks for reading! In this article, you learned how to configure status checks and branch protections on your repo. By adding branch protections you've added safeguards that ensure contributions are reviewed and tested before they can be merged. Reviewing and testing every pull request ensures high-quality contributions and makes your code easier to support and ship forevermore.

Want to Connect?

If you found the information in this tutorial useful please subscribe on Medium, follow me on GitHub, and/or subscribe to my YouTube channel.