Dynamically Add Reviewers to a Pull Request

Using this script, you can dynamically add default and mandatory reviewers based on a script when a pull request (PR) is created or updated. 

You can combine a script that sets reviewers with a condition so that you can automate some PR functions, like:

  • Include a senior reviewer from the onsite team when a pull request from an outsourced team is created
  • Include the mentor of a new team member when a PR is created by the new team member
  • Include mandatory reviewers on the pull request, which are determined dynamically based on naming standards and AD groups

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 are not 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. Navigate to Admin > ScriptRunner > Listeners > Create Listener if you want to add the listener globally.

    You can also add at:

    • Project Level: Navigate to Project Settings >ScriptRunner > Listeners > Create Listener
    • Repository Level: Navigate to Repository Settings >ScriptRunner >Listeners > Create Listener
  2. Select Dynamically Add Reviewers to Pull Requests.
  3. Add an optional Note to describe what the listener does.

  4. Select the Projects/Repositories you want to work with.

    For Project/Repository level this field is not available.

  5. You may add your Condition, which is optional, by writing code on the Script tab or use an existing script on the File tab.

    • If Condition is left blank, the field evaluates to True.
    • Select Show Snippets for conditions examples. 
    • The File tab is not available for Project/Repository level.

  6. Enter a Configuration Script to dynamically add default and/or mandatory individual and/or groups of reviewers. 

    In order to add the reviewers, there are some methods available in this script binding that receives user names and group names.

    You can select Show Snippets to see the following example.

     
    addMandatoryUsers("user", "userB")
addDefaultUsers("userC")
addMandatoryGroups("mandatory")
addDefaultGroups("default", "defaultB")

    Each method accepts one or more user names or group names.

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

    On the other hand, mandatory 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 a Dynamically Add Reviewers to a Pull Request listener with the 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.

  7. Select Add to save the listener.

Example: Dynamically Add Reviewers to All PRs

  1. If this is a global configuration, first select all Projects/Repositories for which this listener should be applicable to add the reviewers to all PRs. 
  2. Leave Condition blank, and it will evaluate to True. 

  3. Add a Script with the snippet below to set the Default Users, Default Groups, Mandatory Users, and Mandatory Groups  

     
    addMandatoryUsers("user", "userB")
addDefaultUsers("userC")
addMandatoryGroups("mandatory")
addDefaultGroups("default", "defaultB")

  4. Select Add. 

    You can see the populated fields in the following image: 

    Result: When the PR dialog appears, the following reviewers will be added to the PR:

    • The user, userB, and userD (who was a part of the mandatory group) will be set as Mandatory Reviewers.
    • The userC, userE (part of default group), and userF (part of defaultB group) as a Default User.

      Since user, userB and userD users were added as Mandatory Reviewers, they cannot be removed from the PR. If they are removed, a merge check will not allow the PR to be merged until they have been added back.

On this page