About pull requests
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.
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.
- 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.
Require approval from a specified number of reviewers on pull requests.
Encourage traceability by checking for linked work items on pull requests
Check to see that all comments have been resolved on pull requests.
Add one or more policies to validate code by pre-merging and building pull request changes. Can also enable or disable policies.
Add one or more policies to require other services to post successful status to complete pull requests. Can also enable or disable policies.
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:
- Branch policies overview
- How to configure branch policies
- Branch permissions
- Use Azure Functions to create custom branch policies
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:
- Customize and extend pull request workflows with pull request status
- Create a PR status server with Node.js
- Configure a branch policy for an external service
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.