Review code with pull requests
Azure Repos | TFS 2018 | TFS 2017 | TFS 2015 | VS 2017 | VS 2015
Create pull requests to review and merge code in a Git project. Pull requests let your team review code and give feedback on changes before merging it into the master branch. Pull requests can come from either topic branches within the same repository or from a branch in a fork of the original repository. Reviewers can step through the proposed changes, leave comments, and vote to approve or reject the code.
New to pull requests? Learn more about how to get feedback with Git pull requests.
View and manage your pull requests
Your web portal uses either the New navigation or Previous navigation user interface. Choose the New navigation tab if the New Navigation feature is enabled. You'll see a vertical sidebar along with other navigational features when New Navigation has been enabled for the signed-in user or the organization. Choose Previous navigation when you see a top-level, blue-bar—indicating that New navigation isn't enabled. For more information, see Web portal navigation.
Choose the New navigation tab for guidance. Azure DevOps Server 2019 supports the New Navigation user interface. For more information, see Web portal navigation.
Choose the Previous navigation tab for guidance. TFS 2018 and earlier versions only support the previous navigation user interface. For more information, see Web portal navigation.
Create a new pull request
Create a new pull request from:
- Pushed feature branches to your Git repo
- The Development section in a linked work item
- From the Pull requests page on the web
- Team Explorer in Visual Studio
- Using the Azure DevOps Services CLI
After pushing a branch
From a linked work item
Create a pull request directly from a work item linked to the branch.
- From the Backlogs or Queries tab in the Work view , open the work item with the linked branch.
- In the Development area of the work item, there's a link to create a pull request under the branch name.
Select the link to go to a page where you can enter your pull request details and create the pull request.
From the Pull requests page on the web
Create pull requests from any branch from the Pull Request page on the web.
Select New pull request in the upper right to go to a page where you can enter your pull request details and create the pull request. Pick the branch you wish to have reviewed and the branch you want to merge the changes into, such as the master branch.
From Visual Studio
Initiate pull requests directly from Visual Studio.
- Connect to your Project from Visual Studio.
- Open Team Explorer (select View, then Team Explorer or use the
Open Pull Requests in Team Explorer by selecting the Home icon and choosing Pull Requests.
From the Pull Requests view you can view pull requests opened by you, assigned to you, and you can create new pull requests. Select New Pull Request to open up a web browser where you can create the new pull request in the Azure DevOps Services web portal.
You can also initiate pull requests from Visual Studio from the Branches view in Team Explorer by right-clicking the branch name and selecting Create pull request while connected to your project.
From the Azure DevOps Services CLI
You can now manage pull requests and other resources in Azure DevOps Services and Team Foundation Server 2017 Update 2 or later from the command line with the Azure DevOps Services CLI.
For a list of commands to create and manage pull requests, see Manage pull requests.
For more information about working with the Azure DevOps Services CLI, see Get started with the Azure DevOps Services CLI.
Draft pull requests
Sometimes you may want to create a pull request but you aren't ready to send it to the entire team for review. Draft pull requests allow you to indicate that a pull request is a work in progress, without resorting to title prefixes such as WIP or DO NOT MERGE. When the pull request is ready for review, you can publish it, and begin (or resume) the full review process.
- Draft pull request differences
- Create a draft pull request
- Publish a draft pull request
- Mark as draft
Draft pull request differences
Draft pull requests have the following differences from published pull requests.
- Build validation policies are enabled but not run automatically, but they can be manually queued by selecting the ... menu beside the build in the pull request.
- Voting is disabled while in draft mode.
- Required reviewers are not automatically added.
- Notifications are sent while in draft mode, but only to reviewers that you explicitly add to the draft pull request.
Draft pull requests are displayed in the pull requests list with a special badge.
Create a draft pull request
To create a draft pull request, choose Create as draft when creating the pull request.
If you start your pull request title with WIP, Create as draft is selected as the default option.
Publish a draft pull request
When you're ready to have the pull request reviewed and completed, you can publish it.
When a pull request is published, required reviewers are assigned and notified, policies are evaluated, and voting is enabled.
Mark as draft
To mark an active pull request as a draft, choose Mark as draft. Marking a pull request as draft resets all votes, and if your pull request has any votes you'll be asked to confirm.
Add detail to your pull request
Link work items and describe the changes in the branch to make it easier for others to see what problem you are trying to solve. Change the pull request title, add a detailed description, add reviewers, link work items, and make comments to explain your changes. When you're ready to create the pull request and have your changes reviewed, select Create.
Don't worry if you don't have all of the work items, reviewers, or details ready when you create your pull request - you can add them now when you create the pull request, and you can also add or update all of these items later after you create the pull request.
Help reviewers using pull request labels
Sometimes it's important to communicate extra information about a pull request to the reviewers. Maybe the pull request is still a work in progress, or it's a hotfix for an upcoming release - so you append some extra text in the title, perhaps a "[WIP]" prefix or "DO NOT MERGE". Labels now provide a way to tag pull requests with extra information that can be used to communicate important details and help organize pull requests.
To add a label when creating a pull request, choose Add label. After a pull request is created you can manage labels in the Labels section.
In a future release, we'll make labels even more useful by making it easier to filter pull requests using labels.
Add and remove reviewers
Link work items
Edit pull request title and description
Update the title of a pull request by clicking the current title and updating the text. Choose the save icon to save changes or select undo to discard your changes.
Edit the pull request description by selecting the edit link that appears when you hover over the existing description.
Keep these fields up to date so reviewers know what the changes in the pull request are trying to accomplish.
Review a pull request
The Overview tab shows the current state of the pull request at a glance. Review the title, description, and discussion to get an understanding of the proposed changes and see issues brought up by other reviewers.
If you need to make a change to the code as part of your review, starting with Visual Studio 2017 Update 6 you can checkout the source branch from a pull request directly from the Pull Requests view in Team Explorer. Right-click the desired pull request and choose Checkout Source Branch.
Browse code changes
Select the Files tab to view the changes made to the source branch relative to the target branch of the pull request.
The size limit for files in the files view and the diff view is 5 MB. To view and diff files larger than 5 MB, you can download the file and view it using a local diff tool on your machine.
Review previous versions of the code pushed to the source branch of the pull request from the All updates drop-down. A new version is added to the list in the drop-down and on the Updates tab every time the branch is updated in Azure Repos.
The diff view updates as you select different changes, showing the differences between the files in the currently selected and previous version in the pull request. Catch up with a pull request after being away from it for awhile by stepping through changes made since your last review.
Browse a list of changes by push from the author using the Updates tab.
You can select and view changes made in commits on the branch in the Commits tab.
Add comments to the pull request to make suggestions, reply to previous comments, and point out problems with the proposed changes.
Comment inline in the Files tab in your pull request by selecting the comment icon ().
Leave feedback not tied to a specific code change by commenting in the Overview tab.
Reply directly to the author or other reviewers by using
@username and reference work items using
#workitemID in your comments. You can also reference other pull requests using
Update comment status to let reviewers know what you are doing to address the concerns brought up in their review. New comments start in Active status and can be updated in the conversation using the Resolve and Reply & resolve buttons.
Additional options are available in the comment resolution drop-down.
- Active: Comment is still under review.
- Pending: The issue in this comment will be addressed, but isn't fixed yet.
- Resolved: The issue brought up in this comment has been fixed.
- Won't Fix: The suggestion in the comment is noted, but won't make changes in this pull request to address it.
- Closed: Discussion for this comment is closed.
Vote on the changes
Vote on the changes in a pull request by choosing an option from the button on the upper right. The default option is Approve, but you can select other options from the drop-down:
- Approve: Agree with the proposed changes in the pull request as-is.
- Approve with suggestions: Agree with the pull request, but provide optional suggestions to improve the code.
- Wait for author: Do not approve the changes, and ask the author to review your comments. The author should let you know when you should re-review the code after they have addressed your concerns.
- Reject: The changes aren't acceptable. If you are voting this way, you should leave a comment in the pull request detailing why the changes were rejected.
- Reset feedback: Choose Reset feedback to remove your vote.
The number of required approvals in a pull request can be set from the branch policy for the branch. Pull requests can be completed if the number of required approvals is met, even if other reviewers have rejected the changes. Votes in a pull request can optionally be reset when new code is pushed to the branch by checking Reset code reviewer votes when there are new changes when configuring the Require a minimum number of reviewers branch policy.
Best practice: At least two reviewers should review and approve the changes in a significant pull request.
Update code in response to feedback
Update your code in response to comments by creating a new commit with the changes and pushing the updates to the branch in your Git repo. You can make quick updates to your branch directly from the Files tab in the Code view on the web.
Change the target branch of a pull request
For most teams, nearly all pull requests target the same branch, such as
develop. However, in the case where you do need to target a different branch, it's easy to forget to change the target branch from the default. With the new feature to change the target branch of an active pull request, this is now a simple action. To learn how, see Change the target branch of a pull request.
Complete the pull request
Complete your pull request after the reviewers approve of the changes by selecting Complete in the upper right of the pull request view.
- Complete: Complete the pull request now and merge the changes to the target branch.
- Set auto-complete: If you have branch policies, you can choose Set auto-complete to configure the pull request to close once all branch policies are met.
- Abandon: Choose Abandon to close the pull request without merging the changes.
Enter the message used for the merge commit and update the pull request description as needed in the dialog that follows.
- Check Complete linked work items after merging to complete any linked work items.
- Check Delete
<branch name>after merging to delete the source branch from the pull request.
- Check Squash changes when merging to squash merge your pull request.
- Check Override branch policies and enable merge to force merge even if all branch policies haven't been satisfied. This option is only available if you have Exempt from policy enforcement permissions.
Linked work items are also updated showing the pull request completion.
Select Auto-complete from the Complete button drop-down to complete the pull request and merge the changes as soon as all branch policies are met. Auto-completion lets you skip having to come back to the pull request to complete it after the build finishes successfully and the reviewers approve the changes. When the conditions are satisfied for auto-complete, the pull request is completed and you are notified via email. If there is a conflict or an error completing the pull request, you will get an email notifying you of the issue so you can resolve it.
Once auto-complete has been set, the pull request displays a banner confirming that the changes will be merged as soon as the policies are satisfied. Select Cancel auto-complete to turn off auto-complete and return the pull request to an active state. Starting with TFS 2018 Update 2, the banner displays the outstanding list of policy criteria.
The Auto-complete option is available in Azure Repos and TFS 2017 and higher, and is only present when you have branch policies that must be satisfied before the pull request can be completed. If you don't see Auto-complete, it is because you don't have any branch policies. For more information, see Branch policies.
Abandon your changes
Abandon pull requests when you decide the work in the feature branch should not be merged by selecting Abandon from the drop-down on the Complete button. The abandoned pull request will still be viewable on the web and stays linked to work items.
Reactivate an abandoned pull request at any time by selecting the pull request from the Abandoned tab in the Pull Request view and selecting Reactivate.
Receiving notification of pull request updates
Subscribe to email alerts to get notified when changes are made to your pull requests.
By default you are subscribed to several common pull request notifications. For a complete list of default notification subscriptions, see Out-of-the-box (OOB) or default subscriptions
Revert a pull request
Undo the changes made in a pull request by opening the completed pull request and selecting Revert. When you revert a pull request in this way, you create a new branch with changes that will undo the pull request for an existing target branch in your repo.
In the dialog that appears, pick the branch where you want to undo the pull request changes in the Target branch selector and the name of a new branch where the reverted changes will be created in the Topic branch name field, then select Revert. Select Create pull request to merge the newly created branch in a second pull request to complete the revert.
The branch created during this revert has a single commit that reverts the file changes in the pull request. The branch does not contain a reverted commit for each of the commits merged in the original pull request.
Cherry-pick a pull request
Copy changes made in a pull request to another branch in your repo by selecting Cherry-pick while viewing the completed pull request or selecting Cherry-pick from the ... menu while viewing an active pull request. Cherry-picking a pull request in this way creates a new branch with the copied changes that you then merge into a target branch in a second pull request.
In the dialog that appears, enter the branch you want to merge the copied changes into in the Target branch field and a new branch that will contain the copied changes in the Topic branch name field, then select Cherry-pick. If there are no conflicts between the target branch and the newly created topic branch, you can then select Create pull request to merge the topic branch into the target branch to complete the cherry-pick.
Set a new default branch
This step requires Edit Policies permissions on your Git repo.
Configure your Git repo to use a different default branch to merge code into when your team creates new pull requests.
This is useful when you want to use a branch other than
master for new changes or need to change your main line of development in your repo.