GitHub was launched in 2008 and since then has become a massively popular platform for hosting source code, both for private and open-source projects. That’s why performing—or receiving—a code review on GitHub is part of the daily lives of many software engineers.

That’s what this post is about: the right way to do a code review on GitHub. We’ll start with some fundamentals, briefly covering the importance of code reviews and how they relate to GitHub pull requests. Then, we’ll walk you through how the code review process works on GitHub, sharing tips on how to do it the best way.

Before wrapping up, we’ll share some final thoughts and tips. Let’s dig in.

Table of Contents

Code Review on GitHub: The Fundamentals

Before exploring the anatomy of a GitHub code review, let’s walk through some basics first.

The Importance of Code Reviews

When it comes to improving the quality of a codebase and reducing technical debt, there’s probably no technique more effective than code reviews—with automated testing being the honorable exception. We do have another post on what code reviews are and why they matter as well as a post on what you need (and don’t need) in your code review checklist, both of which you should check it out.

Besides improving code quality, peer reviews also have another great advantage: they help to spread knowledge among team members. Through frequent code reviews, engineers can learn about different areas of the code, which helps their team achieve true collective code ownership, thus reducing their bus factor. This is especially important in a remote setting, where face-to-face knowledge transmission isn’t possible.

Code Review != Pull Request

With the importance of code reviews out of our way, there’s another point we need to discuss: the differences between a code review and a pull request. Sure, these two processes are related, but they’re not the same. It’s possible to use one or the other, or use both together—which we recommend. You could try using neither, but we definitely don’t recommend that.

For instance, the following patterns are all possible:

  • Merging pull requests without review and then reviewing the code afterward
  • Using pair programming as a replacement for reviews—in my opinion, they don’t really substitute, but that’s another conversation
  • Performing code reviews even without using Git—in a previous job, we used Team Foundation Version Control and a Visual Studio plugin so we could have code reviews
  • Having pull requests on GitHub just for “auditing” purposes and merging them immediately after

A Good Pull Request Process Makes Your Code Review Better

Finally, since we do recommend you perform your code reviews during pull requests, it’s essential you understand the importance of a great pull request process.

Speed is paramount, especially in a continuous integration/continuous software development paradigm. Small pull requests make it easier for the reviewer to review the code, which reduces the time it takes for the pull request to be picked up and completed. The rule of thumb is: smaller pull requests and more pull request merges over larger pull requests and fewer merges.

Paradoxically, speeding up development time also improves the quality of the shipped code! This is what LinearB’s CEO calls “the Bicycle Syndrome.”

Having a standardized pull request process makes the lives easier for both reviewer and reviewee. Since both sides know what to expect, there’s less rework and less time wasted.

Thankfully, you don’t have to create and execute on a pull request process all on your own. You can rely on code review tools designed to make the process easier and more effective. GitHub’s UI offers great features to facilitate code review, allowing the reviewer to compare diffs, leave comments on specific lines, and even suggest code changes on the spot.

Pairing GitHub with LinearB’s gitStream tool equips you with a powerful system that will be the basis for a successful code review process. With workflow automation and metrics, LinearB helps your teams keep pull request sizes small or ensure that they’re being thorough as they review requests.

How to Do Code Reviews on GitHub the Right Way

Do you know how a code review on GitHub works? How do you do it the right way?

It All Starts With a Pull Request

As I said earlier, pull requests and code reviews aren’t interchangeable terms, and even GitHub’s UI makes that distinction clear. However, since the pull request is a great “place” to centralize discussions about a proposed change, it makes sense to use it as the start of the code review process as well.

Let’s start with a public repository like this one I prepared for this post. To contribute to a public repo, you’d usually have to fork it, clone your fork locally, create a new branch for your changes, commit and push your changes, and finally open a pull request. That’s not necessarily hard, but it would make this post longer than needed, and this isn’t a GitHub or Git tutorial.

Let’s make it easier. Go to the repo, click on the README.md file, and then click on the pencil icon on its right upper corner. You’ll then be able to edit the file as you wish.

When you’re done, provide and title and description and click on Propose Changes.

propose changes code review on github

That will cause several things to happen:

  • GitHub will set up a new fork of the repository for you.
  • It will also create a new branch and commit the change you made to that branch.
  • Finally, it will submit a pull request from this newly-created branch.

Oh, by the way, I’m keeping this repository online so that if you want to practice making pull requests, you can go there to actually create one and I’ll accept it.

The Reviewer Analyzes the Changed Lines of Code

So, I actually went there and created a pull request. It’s kind of weird to review a pull request that I myself sent, but c’est la vie. Here’s my view as the repo’s maintainer:

github code review

As you can see, there’s quite a lot going on there. Let’s break it down:

  1. The Conversation tab shows the comments both the reviewer(s) and the author left. There are currently no comments.
  2. The Commits tab shows the individual commits contained in the pull request.
  3. The Checks tab displays checks and verifications that can be done in a CI/CD process. You can set that up by using GitHub actions.
  4. The Files changed tab displays the individual files touched by the change, so the reviewer can review them one by one.
  5. The Merge pull request button allows me to close the pull request and incorporate its changes to the main branch.

Going to the Files changed tab, this is what I see:

github code review files changed

The GitHub UI indicates very clearly:

  • which file was changed
  • what the change was
  • which portions of the file we’re seeing (indicated by the -1,3 and +1,3—that is, for the original (-) and changed (+) version we’re seeing three lines, starting at line 1).
  • the actual information that was deleted and replaced.

The Reviewer Can Leave Single Comments or Initiate a “Formal” Review

As a reviewer, there’s quite a lot of flexibility regarding how you handle the changes. For starters, you can leave general comments or add comments to specific files and lines.

This is a general comment:

github code review comment

As you can see, you can choose to close the pull request with a comment, effectively rejecting the change. In this case, I’ll simply click on the Comment button and save my comment.

I’ll now comment on a specific line. First, I’ll go to the Files changed tab. There, I can hover over the lines of both the old and new versions of the file, and a plus sign button appears:

github code review comment on specific line

By clicking on the button, I can leave a comment:

github code review comment on specific line

It’s possible to add the comment as a “single comment” or to start a review. Single comments aren’t that exciting, so I’ll Start a review. Here’s what I see after pressing the button:

github code review finish your review

As you can see, there’s a Finish your review button I can use when I’m done reviewing the changes. In a real-world scenario, you’d typically finish the review after looking at all the changed files and leaving suggestions, questions, and observations as needed.

After clicking on the button, you’ll see three options:

  1. Comment. With this option, you just leave a comment without necessarily approving the changes.
  2. Approve. This approves the changes. It doesn’t merge the branch and close pull request, though.
  3. Request changes. You leave feedback that the author must address.

The Author Can Reply to the Comments and Update the Code

From now on, the process is relatively straightforward:

  • The author can reply to the comments, and other reviewers can jump on the conversation.
  • GitHub allows you to link to issues, commits, and even other pull requests. It’s also possible to mention users, inviting them to join the conversation.
  • The author can commit more changes and push them to their browser, and GitHub will automatically pick up those changes and update the pull request.

Fix Your Pull Requests and Reap the Benefits

As you read in this post, doing a code review on GitHub is, generally speaking, an easy and lightweight process. And, thanks to GitHub’s great UI, it’s also mostly intuitive.

However, that doesn’t mean the pull request process isn’t without its pains. Reviewers suffer from large, complex pull requests. Authors suffer when their changes take a long time to be reviewed and merged. The whole team suffers because stuck PRs can lead to a number of problems, including conflicts.

The good news is it doesn’t have to be this way. Pull requests can be fixed, and you can do it with the help of automation tools that enable you and your team to be on top of your PRs.

Want to learn how to implement custom dev workflow automation to cut code review time by up to 40%? Watch this hands-on workshop to set up the free gitStream tool to automatically:

:white_check_mark: Classify and route pull requests
:white_check_mark: Add estimated review time to PRs
:white_check_mark: Apply custom rules

gitStream Workshop: Getting started with workflow automation

gitStream product lead, Ofer Afias, will take you through a live demo of the three core functions when getting started with gitStream workflow automation to scale your team efficiently and improve your developer experience.

At the end of the day, if you have a streamlined and standardized pull request process, your team will be able to make the most out of code reviews. So, before wrapping up, here are a few best practices regarding pull requests:

  • Keep your pull requests small and focused.
  • Start the pull request earlier; you don’t need to wait until you’re finished to start collecting feedback.
  • Add plenty of context to the pull request, including a well-written description, links to relevant resources, screenshots, and whatever you can use to help the reviewer understand the change.

For more tips on pull requests, check out our full blog post on the topic.

Thanks for reading, and until the next time.