Auto-Add Reviewers to a Pull Request

Using this script, you can automatically add reviewers when a pull request (PR) is created. You can combine reviewer settings with a condition so that you can automate some PR functions, like:

  • Pull requests from an outsourced team automatically include a senior reviewer from the onsite team

  • The mentors of new team members are automatically added as reviewers

From Bitbucket 4.8 there is a feature that allows you to assign default reviewers for pull requests: BSERV-2924. These features can work alongside each other without interfering with each other, with one notable caveat. If you add default reviewers using the Bitbucket feature and set a certain number of them to be required, then reviewers added using the ScriptRunner listener will not be able to approve or reject a pull request until one of the Bitbucket reviewers has weighed in. This is consistent with how Bitbucket Server’s default reviewers feature normally behaves. In short, the reviewers that are required to weigh in by Bitbucket Server settings have the first say on a pull request.

To set up this listener, follow these steps: 

  1. Add an optional Note to describe what the listener does.
  2. Select the Projects/Repositories you want to work with.

  3. Enter your Condition by writing code on the Script tab or use an existing script on the File tab.
    Select Show Snippets for examples. 

    If Condition is left blank, the field evaluates to True. 

  4. Enter Default Users and/or Default Groups to automatically add individual or groups of reviewers. 

    These reviewers are automatically added to the PR dialog when the PR is created, but the PR author can remove them.

    Only users that are active and have the necessary permissions in the repository are added.

  5. Enter Mandatory Users and/or Mandatory Groups to automatically add individual or groups of reviewers. 

    These reviewers cannot be removed. There is a behind-the-scenes merge check that blocks you from removing configured mandatory reviewers from a PR. If you set up an Auto-Add Reviewers to a Pull Request listener with mandatory reviewer(s) and they are removed from a PR, the merge check prevents a merge until the mandatory reviewer is added back.

    Use mandatory reviewers to enforce that certain users get to review changes to important or sensitive code, or branches.

    Only users that are active and have the necessary permissions in the repository are added.

  6. Select Add to save the listener.

Example: Add Reviewers to All PRs

  1. Add a Note to indicate what the listener is, like Add authorised devs to PR. 
  2. Select All (current and future) for Projects/Repositories to add the reviewers to all PRs. 
  3. Leave Condition blank, and it will evaluate to True. 
  4. Add Mr XYZ as a Default User. 
  5. Add authorised-devs to Default Groups. 
  6. Add Mr Senior Dev to Mandatory Users. 
  7. Leave Mandatory Groups blank. 

  8. Select Add. 

    You can see the populated fields in the following image: 

    Result: When the PR dialog appears, Mr Senior Dev, Mr XYZ, and Mr Admin (who was a part of the authorised-devs group) were added to the PR. 

    Since Mr. Senior Dev was added as a Mandatory User, so he cannot be removed from the PR. If he is, a merge check will not allow the PR to be merged until he has been added back.

Retrieving reviewers in a merge check

You can retrieve the list of reviewers added by this built-in script in a merge check.  Merge checks help you write your own rules around which reviewers should approve a PR and when. Use the following code to retrieve a list of reviewers:

groovy
import com.atlassian.bitbucket.pull.PullRequestParticipant
import com.atlassian.bitbucket.user.ApplicationUser

 // Reviewers set by ScriptRunner listeners.
Set<ApplicationUser> mandatoryUsers = mergeRequest.pullRequest.autoAddedReviewers.mandatoryUsers
Set<ApplicationUser> defaultUsers = mergeRequest.pullRequest.autoAddedReviewers.defaultUsers
Set<String> mandatoryGroupNames = mergeRequest.pullRequest.autoAddedReviewers.mandatoryGroups
Set<String> defaultGroupNames = mergeRequest.pullRequest.autoAddedReviewers.defaultGroups

 // All pull request reviewers
Set<ApplicationUser> allReviewers = mergeRequest.pullRequest.autoAddedReviewers.allUsers
 // Or
Set<PullRequestParticipant> allReviewersFromPR = mergeRequest.pullRequest.reviewers
On this page