Reviewing proposed changes in a pull request

In a pull request, you can review and discuss commits, changed files, and the differences (or "diff") between the files in the base and compare branches.

Tool navigation

In this article

About reviewing pull requests

You can review changes in a pull request one file at a time. While reviewing the files in a pull request, you can leave individual comments on specific changes. After you finish reviewing each file, you can mark the file as viewed. This collapses the file, helping you identify the files you still need to review. A progress bar in the pull request header shows the number of files you've viewed. After reviewing as many files as you want, you can approve the pull request or request additional changes by submitting your review with a summary comment.

Tip

You can find a pull request where you or a team you're a member of is requested for review with the search qualifier review-requested:[USERNAME] or team-review-requested:[TEAMNAME]. For more information, see "Searching issues and pull requests."

Starting a review

  1. Under your repository name, click Pull requests.

    Screenshot of the main page of a repository. In the horizontal navigation bar, a tab, labeled "Pull requests," is outlined in dark orange.

  2. In the list of pull requests, click the pull request you'd like to review.

  3. On the pull request, click Files changed.

    Screenshot of the tabs for a pull request. The "Files changed" tab is outlined in dark orange.
    You can change the format of the diff view in this tab by clicking and choosing the unified or split view. The choice you make will apply when you view the diff for other pull requests.

    Screenshot of the "Files changed" tab for a pull request. The "Diff view" menu is outlined in dark orange.

    You can also choose to hide whitespace differences. The choice you make only applies to this pull request and will be remembered the next time you visit this page.

  4. Optionally, filter the files to show only the files you want to review or use the file tree to navigate to a specific file. For more information, see "Filtering files in a pull request."

  5. Hover over the line of code where you'd like to add a comment, and click the blue comment icon.

    Screenshot of a diff in a pull request. Next to a line number, a blue plus icon is highlighted with an orange outline.

  6. Optionally, you can add a comment on multiple lines. You can click the line number of the first line you want to comment on and drag down to select a range of lines, then click the blue comment icon on the last line you want to comment on. Alternatively, you can click the blue comment icon next to the first line you want to comment on, then drag down to the last line you want to comment on.

  7. In the comment field, type your comment.

  8. Optionally, to suggest a specific change to the line or lines, click , then edit the text within the suggestion block.

    Screenshot of a review comment box. The file diff icon to suggest a specific change is outlined in dark orange.

  9. To comment directly on a file, to the right of the file, click and type your comment.

    Screenshot of an image file on the "Files changed" page of a pull request. To the right of the image file, a comment icon is highlighted with an orange outline.

  10. When you're done, click Start a review. If you have already started a review, you can click Add review comment.

Before you submit your review, your line comments are pending and only visible to you. You can edit pending comments anytime before you submit your review. To cancel a pending review, including all of its pending comments, click Review changes above the changed code, then click Abandon review.

Screenshot of the comment field for a review. The "Abandon review" button is outlined in dark orange.

You can use GitHub Codespaces to test, run, and review pull requests.

  1. Open the pull request in a codespace, as described in "Using GitHub Codespaces for pull requests."

  2. In the Activity Bar, click the GitHub Pull Request view. This view only appears when you open a pull request in a codespace.

    Screenshot of the VS Code Activity Bar. The mouse pointer is hovering over an icon displaying the tooltip "GitHub Pull Request."

  3. To review a specific file, click the Open File icon in the Side Bar.

    Screenshot of the "GitHub Pull Request" side bar. A file name is highlighted with a dark orange outline.

  4. To add review comments, click the + icon next to the line number. Type your review comment and then click Start Review.

    Screenshot of a comment being added, reading "Yes, I agree, this is clearer." The "Start Review" button is shown below the comment.

  5. Optionally, you can suggest a change that the author of the pull request can click to commit if they agree with your suggestion. To do this, click and hold the + sign next to the first line you want to suggest changing, then drag the + sign to the last line you want to suggest changing. Then click Make a Suggestion in the comment box that's displayed.

    The lines you selected are copied into the comment box, where you can edit them to suggest a change. You can add a comment above the line containing ```suggestion to explain your suggested change.

    Click Add Comment to add your suggestion to the pull request.

    Screenshot of a suggested change. The "Make a Suggestion" and "Add Comment" buttons are shown below the suggested change.

  6. When you are finished adding review comments, from the Side Bar you can choose to either submit the comments, approve the changes, or request changes.

    Screenshot of the side bar showing the dropdown options "Comment and Submit," "Approve and Submit," and "Request Changes and Submit."

For more information on reviewing pull requests in GitHub Codespaces, see "Using GitHub Codespaces for pull requests."

Reviewing dependency changes

If the pull request contains changes to dependencies you can use the dependency review for a manifest or lock file to see what has changed and check whether the changes introduce security vulnerabilities. For more information, see "Reviewing dependency changes in a pull request."

  1. On the pull request, click Files changed.

    Screenshot of the tabs for a pull request. The "Files changed" tab is outlined in dark orange.

  2. On the right of the header for a manifest or lock file, display the dependency review by clicking the rich diff button.

    Screenshot of the "Files changed" tab of a pull request. The button to display the rich diff, labeled with a file icon, is outlined in dark orange.

  3. You may also want to review the source diff, because there could be changes to the manifest or lock file that don't change dependencies, or there could be dependencies that GitHub can't parse and which, as a result, don't appear in the dependency review.

    To return to the source diff view, click the button.

    Screenshot of the "Files changed" tab of a pull request. The button to display the source diff, which is labeled with a code icon, is outlined in dark orange.

Marking a file as viewed

After you finish reviewing a file, you can mark the file as viewed, and the file will collapse. If the file changes after you view the file, it will be unmarked as viewed.

  1. On the pull request, click Files changed.

    Screenshot of the tabs for a pull request. The "Files changed" tab is outlined in dark orange.

  2. On the right of the header of the file you've finished reviewing, select Viewed.

    Screenshot of the header of a file. The "Viewed" option is outlined in dark orange.

Submitting your review

After you've finished reviewing all the files you want in the pull request, submit your review.

  1. On the pull request, click Files changed.

    Screenshot of the tabs for a pull request. The "Files changed" tab is outlined in dark orange.

  2. Above the changed code, click Review changes.

    Screenshot of the "Files changed" tab of a pull request. The "Review changes" button is outlined in dark orange.

  3. Type a comment summarizing your feedback on the proposed changes.

  4. Select the type of review you'd like to leave:

    • Select Comment to leave general feedback without explicitly approving the changes or requesting additional changes.
    • Select Approve to submit your feedback and approve merging the changes proposed in the pull request.
    • Select Request changes to submit feedback that must be addressed before the pull request can be merged.

  5. Click Submit review.

Tip

  • The Request changes option is purely informational and will not prevent merging unless a ruleset or classic branch protection rule is configured with the "require a pull request" option. If configured and a collaborator with admin, owner, or write access to the repository submits a review requesting changes, the pull request cannot be merged until the same collaborator submits another review approving the changes in the pull request.
  • Repository owners and administrators can merge a pull request even if it hasn't received an approving review, or if a reviewer who requested changes has left the organization or is unavailable.
  • If both required reviews and stale review dismissal are enabled and a code-modifying commit is pushed to the branch of an approved pull request, the approval is dismissed. The pull request must be reviewed and approved again before it can be merged.
  • When several open pull requests each have a head branch pointing to the same commit, you won’t be able to merge them if one or both have a pending or rejected review.
  • If your repository requires approving reviews from people with write or admin permissions, then any approvals from people with these permissions are denoted with a green check mark, and approvals from people without these permissions have a gray check mark. Approvals with a gray check mark do not affect whether the pull request can be merged.
  • Pull request authors cannot approve their own pull requests.

Further reading