Share via

About pull requests

  • Article

TFS 2017 | TFS 2015 | TFS 2013

Visual Studio 2019 | Visual Studio 2017 | Visual Studio 2015

Pull requests (PRs) are a way to change, review, and merge code in a Git repository on Azure Repos. PRs can come from branches within the same repository or from branches in forks of the repository. Teams use PRs to review code and give feedback on changes before merging the code into the main branch. Reviewers can step through the proposed changes, leave comments, and vote to approve or reject the code.

The following video shows the general pull request process. Some terminology and user interface elements might not apply to your Azure DevOps version.

This article describes pull request guidelines and management considerations. For instructions on how to create, view, review, and complete pull requests, see the following articles:

Permissions and prerequisites

  • To view or review PRs, you must be a member of an Azure DevOps project with Basic access or higher. If you aren't a project member, get added.
  • To contribute to a PR, you must be a member of the Readers security group or have the corresponding permissions.
  • To create and complete a PR, you must be a member of the Contributors security group or have the corresponding permissions.

To learn more about permissions and access, see Default Git repository and branch permissions and About access levels.

Quality feedback for pull requests

High-quality reviews start with high-quality feedback. Here are some keys to great PR feedback:

  • The PR owner should have the right people review the PR, and make sure that reviewers know what the code does.
  • Reviewers should give actionable, constructive feedback.
  • Owners and reviewers should comment and reply quickly.

PR owners should:

  • Make sure to select the right reviewers to assign to a PR.
  • Include reviewers that know how the code works.
  • Ask developers working in other areas to share their ideas.
  • Give a clear description of changes.
  • Provide reviewer guidance with pull request templates.
  • Provide a build of the code with the fix or feature running in it.
  • Reply to comments, accepting the suggestion or explaining why the suggested change isn't ideal.
  • For good suggestions outside the scope of the PR, create new work items, branches, and PRs to make those changes.

Reviewers should:

  • Provide feedback on changes they don't agree with.
  • Identify issues and give specific suggestions on what to do differently.
  • Make sure the feedback has clear intent and is easy to understand.
  • Leave comments.
  • Vote on the changes.

Learn more about how to get feedback with Git pull requests.

Branch policies and pull requests

Your team might rely on critical branches in your repo, such as the main branch, to always be in good shape. You can set branch policies to require PRs for any changes on these protected branches, and reject any changes pushed directly to the branches.

You can add more policies to PRs to enforce better code quality in key branches. Extra requirements like a clean build of the proposed code or approval from multiple reviewers can help protect key branches.

You can set the number of required approvals for a PR in a branch policy. You can also set certain reviewers to be required or optional on all or certain PRs. A PR can be set to autocomplete with the required number of approvals, even if other reviewers reject the changes. However, required reviewers must approve PRs before the PRs can merge. It's best practice for at least two reviewers to review and approve changes in a significant PR.

To reset votes whenever a PR author pushes new changes, select Reset code reviewer votes when there are new changes in the Require a minimum number of reviewers branch policy.

The following table summarizes the policies you can define to customize a branch. For an overview of all repository and branch policies and settings, see Git repository settings and policies.

Policy

Default

Description

Require a minimum number of reviewers

Off

Require approval from a specified number of reviewers on pull requests.

Check for linked work items

Off

Encourage traceability by checking for linked work items on pull requests

Check for comment resolution

Off

Check to see that all comments have been resolved on pull requests.

Add Build Validation policies

Off

Add one or more policies to validate code by pre-merging and building pull request changes. Can also enable or disable policies.

Automatically included reviewers

Off

Add one or more policies to designate code reviewers to automatically include when pull requests change certain areas of code. Can also enable or disable policies.

For more information, see:

Define status checks to improve code quality

Pull requests and branch policies let teams enforce best practices for reviewing code and running automated builds. Many teams have further requirements and validations to do on code. To cover these needs, you can integrate PR status checks into the PR workflow. With PR status checks, external services can programmatically sign off on code changes by associating success or failure information with the PR.

For more information, see the following articles:

Multiple merge base issue

In some cases, a PR has more than one true merge base, and this situation can cause security issues. If the files in the PR have different versions between the merge bases, a multiple merge base warning happens. For more information and remediation, see Multiple merge bases.

Next steps