Review and discuss a pull request
The review phase of a pull request typically involves reviewers making comments and the author pushing additional changes and commenting in response, until the pull request is ultimately approved. The pull request author usually starts by adding colleagues as reviewers. Reviewers then leave comments–either on the entire pull request or on a specific part of the code changes–and then update their reviewer status to notify the author that they've completed their review.
You can also create to-do lists that can act as a reminder to ensure that changes made to a pull request before merging are completed by creating a pull request task.
Depending on the feedback provided by reviewers, the author may then update a pull request with new commits. This may be to clean up the code, resolve any outstanding tasks, or improve the quality of the code. They can also apply suggestions to quickly make code changes for minor issues like typos.
Once the cycles of reviewer feedback and new commits has reached a conclusion, a pull request can either be merged to its target branch, or declined if the changes are not to be merged.
Review a pull request
Bitbucket Server allows you to add one or more reviewers to a single pull request who can then approve, or decline the request. Pull requests give those who have access to the repository, the ability to review the quality of the code that’s specified in the pull request.
To review a pull request
- Access the pull request by either following links from an email notification, selecting a notification within the pull request inbox (in the upper-right), or searching for a pull request by clicking Pull requests on the sidebar (read more about searching for pull requests).
- Review the changes and comments left by your teammates within the pull request.
- Leave some feedback about the changes, in any of the views, and use @ mentions to ask questions directly of your colleagues, who will receive a notification after you enter your comment. See the Discuss a pull request section for more details about the various ways you can leave comments, including pull request tasks.
- Finish your review by indicating if you feel the pull request can be merged, or if the author of the pull request needs to make additional changes before you can provide your stamp of approval. Select either the status indicators to let your team know you've reviewed the changes and the ball is now in their court:
- Approve - indicates you've reviewed the changes and the code is ready to be merged.
- Needs work - indicates you've reviewed the changes, but the code is not quite ready to be merged.
Create a Jira issue from a pull request
Bitbucket Server allows you to create a Jira issue directly from a pull request comment or task instead of being forced to leave Bitbucket and return with a created issue.
To create an issue from a pull request comment or task:
- Create a new issue by clicking ... > Create Jira issue.
- Select the Project and Issue type.
- Add a summary, description, and any other fields as needed.
- Click Create issue.
If a created issue is deleted inside Jira, it will continue to be counted as an issue, but will no longer be visible on the pull request.
This feature works best when used to create a spin-off issue to be dealt with after the pull request has been handled.
It is not recommended for adding more workflow items as part of the pull request.
Discuss a pull request
The most important aspect of a pull request is the discussion it generates. You can comment on the entire pull request, a particular file, or on specific lines of code in a file. Comment likes are a quick way of amplifying review feedback – effectively saying "also consider this person's feedback". You can also attach a task to any comment, so actions identified during the review can be easily tracked and resolved. Read more about pull request tasks.
There are three main ways to view changes:
- The overview tab - lists all of the activity for a pull request since the pull request was created.
- The diff tab - highlights which lines of code have been added, deleted, or modified.
- The commits tab - lists all the commits that will get merged. You can click to view a single commit.
Viewing other comments
When updating a pull request, comments that are in older diffs or that have become outdated due to a pull request update will become hidden. To view them, click the other comments counter button at the top of the page to open a dialog box with more context as to why code has changed throughout a pull request. You’ll be able to:
- see a file's activity stream showing comments that are outdated or appear on another diff
- distinguish which comments are actually outdated
- reply to, like, delete, or react to outdated comments the same way you can from the overview tab
Overview
The Overview tab captures all of the team's activity on the pull request in one place, right from the initial creation, through to when it is finally merged (or declined), with all the comments, replies and commits that happen along the way.
You can add a comment on the Overview tab (just under 'Activity'), or reply to a previous comment. Use mentions to alert another Bitbucket Server user to your comment, and use Markdown to add formatting, for example headings or lists.
Diff view
The diff view highlights the changes between the source and target branch. You can choose whether you want to highlight word level changes in the diff, or display details like comments and whitespace changes from the Diff view settings 
icon.
The Unified diff option shows the changes in one continuous column.
The Side-by-side diff lets you easily compare the changes by showing the original file on one side, highlighting removed and modified lines, and then changed files on the other side, highlighting added and modified lines.
Iterative reviews
Within the diff view, using the Change Scope selector, you can select a specific commit to review, or choose to view all changes within a pull request. If you return to a pull request that you previously reviewed, you'll only see the new commits added since you last reviewed the pull request.
Commits
The Commits tab lists all the commits that will get merged (those that are greyed out have already been merged). Clicking through to a commit leaves you inside the pull request context and the commit can be reviewed as part of the pull request..
When viewing a commit you can comment on the whole file, or a particular line of code, just as for a diff, for any file in the commit.
Participants can commit new changes to the branch. Bitbucket Server auto-updates the Commits tab of the pull request, so you can see exactly which commits will be merged. Bitbucket Server is smart about comments, moving them along when lines are added or removed. If a line with a comment gets removed, you can still view the comment in the activity, but Bitbucket Server marks the diff as outdated to let you know that this piece of code has been changed in recent commits.
View a single commit within a pull request
Pull request suggestions
As a reviewer of a pull request, you can suggest a small change to the code by leaving a suggestion right inside the comment or task itself. If you have write access to the source repository, you can commit the suggested change directly in the pull request without further action.
To create a pull request suggestion:
In the comment dialog, click
.Type your suggestion in the code block. You can also add any comments around it.
To apply a pull request suggestion:
- Click Apply suggestion.
- Edit the commit message if required and then click Commit changes to add a new commit to the pull request.
Pull request tasks
You can create a task on the entire pull request, a particular fie, or on specific lines of code in a file to track required work identified during a code review. Convert a task into a comment, or a comment into a task. Anyone with permission to browse a pull request can resolve them. Repository admins and pull request authors can only edit, delete, or convert their own tasks. A Bitbucket Server administrator can enable a merge check that requires all tasks to be resolved before the pull request can be merged. See Checks for merging pull requests.
To create a pull request task, click Add a comment 
or the 
icon on a line of code in the diff view and add your text, then click Create task. Use Markdown to add formatting, images, and attachments to your tasks.
To indicate a pull request task is done, tick the box next to the task.
To see all the unresolved tasks for a pull request, use Shift+T on the pull request page, or click the Open tasks list button.
To see a task in the context of where it was created, in the Tasks window, click the 'View on' linked text.
Find matching code in a pull request
When you want to locate code in a pull request, you can search for it within changed files in the diff view.
To locate code within changed files, click Search code and enter your text into the search field. Only the files containing the match are then displayed expanded in the file tree with the number of occurrences highlighted per file. Easily navigate between occurrences by clicking through each line.
Find files in a pull request
To filter through changed files, click Filter file tree and enter the file name into the field. You can search through files in folders using wildcards.
Some common wildcards supported are *, ?, and **. For example; filtering on **/test/**/*mock*, reveals all files or folders within a directory called test that uses mock in their name. Note that matching is case-insensitive, so the filter will match both text/one/my-mock-test.js and Test/two/MyMockTest.java.
Watching and notifications
You automatically get added as a watcher of a pull request when you are added to the pull request as a reviewer, or when you perform an action related to the pull request (such as adding a comment):
| Action | You're now a watcher |
|---|---|
| You are added as a reviewer |  |
| You add yourself as a reviewer | |
| You comment on a pull request | |
| You reply to a comment | |
| You push to the source branch | |
You can manually add yourself as a watcher by selecting Watch from the selection menu drop-down on the pull request screen.
You can stop watching a pull request by clicking the link in the email notification, or ... > Unwatch on the pull request screen. If you stop watching a pull request, you will not automatically be added as a watcher again if you subsequently perform an action that would otherwise have added you.
Bitbucket Server sends email notifications to watchers when certain pull request events occur. Email notifications are batched by default, but you can change your personal account settings (on the Notification settings tab) so that you get notifications immediately. The following notifications however, are always sent immediately to:
- the reviewers when a pull request is created
- all watchers when a pull request is deleted
- a user when they are added as a reviewer to a pull request
- a user when they are removed as a reviewer from a pull request
- a user when they are mentioned in the description of a pull request
See Notifications for details.