Assign PRs randomly to a specific list of users in Bitbucket Cloud

Every pull request needs a reviewer but selecting the right person is something many teams want to automate. After chatting with a few developers and Atlassian teams, I realized that different teams have different ideas about the logic of assigning a reviewer to a PR.

This blog shows how I implemented one of the most popular options so that you can either use it for your team or take it as a starting point for building your team’s preferred logic.

Forge - Atlassian serverless app development platform

The magic for assigning the reviewers to a PR is implemented using Forge, Atlassian serverless app development platform. Everybody with an Atlassian account can use Forge and you install the app right away on a workspace you administer.

You can always create a new workspace for testing the app and then make it available on your team’s workspace at a later stage.

What does the app do?

With this app installed, every time a pull request is created a user from a predefined list is randomly selected and added as the PR reviewer. A comment is also added mentioning so that it’s clear that the assignment has been performed by the app.

Let's see it in action:

Let’s break down the app into its main components:

• the fetchRepository function is used to load the current repository. This is required to get the name of the default branch.
• the .reviewers file is loaded by the fetchFile function and the list of possible reviewers is saved in the reviewers variable. The version of the file is the one at the head of the default branch, whose name has been retrieved in the first step.
• the getPRAuthor function retrieves the author of the PR
• the author of the PR is removed from the list of possible reviewers. This is because the author cannot be set as a reviewer.
• a random number is generated and used to select one of the possible reviewers
• a reviewer is assigned to the PR via the assignPR function
• the commentOnPR function adds a comment to the PR and the reviewer is mentioned

The app is triggered by a PR creation event (avi:bitbucket:created:pullrequest).

Let’s have a look at the source code

The repository for this app with the instructions on how to install it is available here: https://bitbucket.org/atlassian/forge-bitbucket-assign-pr-reviewer

index.js file

The app logic is defined in a single file called index.js which is available in the src folder, here you’ll find all the functions mentioned above.

Because this app is triggered by a PR creation event, the main prtrigger function has access to the event and context parameters which are used throughout the code to access the identifiers for the workspace (event.workspace.uuid), the repository (event.repository.uuid) and the pull request (event.pullrequest.id).

The repository.mainbranch.name retrieved from the fetchRepository function is used as the commit path parameter when calling the /2.0/repositories/${workspaceUuid}/${repoUuid}/src/${commit}/${path}. This is how we retrieve the most recent version of the file on the main branch.

Fetching the file, the PR author, assigning the PR and adding a comment are operations supported by the Bitbucket REST APIs called using the requestBitbucketForge function.

manifest.yml file

Each Forge app comes with a manifest.yml file that describes it.

For this app, it contains the logic to trigger the index.prtrigger (the prtrigger function in the index.js file) every time a new PR is created. This is done using the avi:bitbucket:created:pullrequest event trigger.

  trigger:
    - key: pullrequest-created-event
      function: main
      events:
        - avi:bitbucket:created:pullrequest
  function:
    - key: main
      handler: index.prtrigger

The manifest file also contains all the required scopes for the app to run the REST API endpoints:

permissions:
  scopes:
    - read:pullrequest:bitbucket
    - write:pullrequest:bitbucket
    - read:repository:bitbucket

The read:repository:bitbucket is required for the GET Get a repository and the GET Get file or directory contents endpoint.

For reading the PR author of a PR via the GET Get a pull request endpoint and adding a comment using the POST Create a comment on a pull request endpoint, the read:pullrequest:bitbucket is needed.

While this app doesn’t add any extension points to the UI, Forge for Bitbucket provides a multitude of UI modules that can be used to show your app information.

Wrapping up

If you too, like many others, have your own preferred way to select users to review a pull request, you can build your own Forge app to do that. This page walks you through a few implementation details of an app and feel free to tweak it, change it, build on it - whatever you need to make it work for you.

Check the repository for this app and install it on your workspace by following the instructions in the README.

We can’t wait to see what amazing alternatives you can come up with! Let us know in the comments!

If you need any help, reach out to our community.