Assign PRs randomly to a specific list of users in Bitbucket Cloud
Tags: webdev, javascript, devops, productivity
Published: 2023-10-04 05:06:26

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](https://developer.atlassian.com/platform/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](https://support.atlassian.com/bitbucket-cloud/docs/create-your-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:
![A PR being automatically assigned](https://community.atlassian.com/t5/image/serverpage/image-id/283124iAEBC36E5748F1A9A/image-size/large?v=v2&px=999)

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](https://developer.atlassian.com/cloud/bitbucket/rest) called using the [requestBitbucketForge](https://developer.atlassian.com/platform/forge/runtime-reference/product-fetch-api/#requestbitbucket) 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](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#forge-app-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](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-repo-slug-get) and the [GET Get file or directory](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-source/#api-repositories-workspace-repo-slug-src-commit-path-get) contents endpoint.

For reading the PR author of a PR via the [GET Get a pull request](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/#api-repositories-workspace-repo-slug-pullrequests-pull-request-id-get) endpoint and adding a comment using the [POST Create a comment on a pull request](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/#api-repositories-workspace-repo-slug-pullrequests-pull-request-id-comments-post) 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](https://developer.atlassian.com/platform/forge/manifest-reference/modules/index-bitbucket) 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](https://bitbucket.org/atlassian/forge-bitbucket-assign-pr-reviewer) 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](https://community.atlassian.com/t5/forums/postpage/board-id/bitbucket-questions?add-tags=forge).