About pull requests
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
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.
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:
Note
For performance and stability reasons, the number of reviewers that can be added to a pull request must be 1000 or less. New pull requests will not be created when adding more than 1000 reviewers, and existing pull requests won't allow you to add more than 1000 reviewers.
Permissions and prerequisites
Repos must be enabled on your project. If the Repos hub and associated pages don't display, see Turn an Azure DevOps service on or off to reenable Repos.
To view or review PRs, you must be a member of an Azure DevOps project with Basic access or higher.
- If you don't have a project, create one or sign up for free.
- 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.
Note
For public projects, users granted Stakeholder access have full access to Azure Repos.
- Repos must be enabled on your project. If the Repos hub and associated pages don't display, see Turn an Azure DevOps service on or off to reenable Repos.
- 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.
For more information 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 do the following tasks.
- 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 or vote on changes
For more information, see 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
Off
Require approval from a specified number of reviewers on pull requests.
Off
Encourage traceability by checking for linked work items on pull requests
Off
Check to see that all comments have been resolved on pull requests.
Off
Control branch history by limiting the available types of merge when pull requests are completed.
Off
Add one or more policies to validate code by pre-merging and building pull request changes. Can also enable or disable policies.
Off
Add one or more policies to require other services to post successful status to complete pull requests. Can also enable or disable policies.
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:
- 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.