Skip to content


Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

Pull Review

coverage report pipeline status npm license

Pull Review

Pull Review assigns pull request reviewers intelligently.

Pull Review looks through the changes in a pull request and assigns the most relevant reviewers, those who have made the largest and most recent contributions to the changed files. The number of reviewers assigned, along with other things, can be configured.

You can use Pull Review through GitHub comments, from chat rooms in Slack/HipChat/etc. using Hubot, on the command line, via API, or as a Docker image.


npm install pull-review

Deploy Pull Review to Heroku


First, add a .pull-review configuration file in your repository:

version: 1

  your_github_username: {}

In order to use Pull Review as a Hubot plugin or in server mode, you'll need a GitHub token. The token must have repo, public_repo, read:user, and read:org scopes.

For details on configuration options, check out the configuration section.


Pull Review used with GitHub

  • In your GitHub repository, go to SettingsWebhooks
  • Click Add webhook
  • Set Payload URL to the Pull Review server URL (
  • Set Content type to application/json
  • Choose Let me select individual events
  • Pick the Issue comment event
  • Click Add webhook

To assign reviewers on a pull request, post /review. To run Pull Review again post /review again.

The public Pull Review server limits some configuration options. However, you can run your own server.


Pull Review used with Hubot

Add pull-review to your external-scripts.json:


Ensure environment variables are set correctly.

You can request review assignments like this:


You can run Pull Review again on a pull request like this:

review again

To notify users on Slack, configuration must include a reviewers section.

Pull Review also adds a pull request preview, for private and public repos.


npm install --global pull-review


pull-review --help

  Usage: pull-review [options] <pull request URL>


    -V, --version                     output the version number
    -r, --retry-review                Retry review
    -d, --dry-run                     Do not assign or notify reviewers
    -t, --github-token <githubToken>  GitHub token to use
    -c, --config-path <configPath>    Pull Review configuration path in repo
    -h, --help                        output usage information


var PullReview = require('pull-review');

  pullRequestURL: '',

  // run Pull Review on a pull request, unassigning current reviewers first
  retryReview: true,

  // run Pull Review on a pull request, but do not assign or notify reviewers
  dryRun: true,

  // run Pull Review with a specific GitHub token

  // run Pull Review with a custom Pull Review configuration
  config: {version: 1},

  // specify a different repo location for the Pull Review configuration
  pullReviewConfigPath: 'config/.pull-review'


The Docker image can be used in CLI mode or in server mode.

# get the Pull Review image
docker pull

# run Pull Review on a pull request
docker run -it -e PULL_REVIEW_GITHUB_TOKEN

# run Pull Review with a specific GitHub token
docker run -it --github-token PULL_REVIEW_GITHUB_TOKEN


You can run your own Pull Review server on Heroku or another host.

Ensure environment variables are set correctly.

Start the server with npm start or by running pull-review with no arguments.

The port is 8080 by default, but can be changed using the PORT environment variable.


Configuration for Pull Review is a YAML/JSON file named .pull-review at the root of the repo.

Check out .pull-review for a documented example of a config file.


Maximum number of files to evaluate in order to assign reviewers. Set to 0 for no maximum.

Default: 5


Minimum number of reviewers to assign.

Default: 1


Maximum number of reviewers to assign.

Default: 2


Maximum number of files per reviewer. If the number of files is over this limit, more reviewers will be assigned up to the maximum number of reviewers. Set to 0 for no maximum.

Default: 0


Maximum number of lines changed across added and modified files per reviewer. If the number of lines is over this limit, more reviewers will be assigned up to the maximum number of reviewers. If max_files_per_reviewer and max_lines_per_reviewer are set, the assignment with the fewest reviewers will be used. Set to 0 for no maximum.

Default: 0


If the minimum number of reviewers isn't found, assign reviewers using path fallbacks and/or at random.

Default: true


If the pull request changes code with fewer authors than this minimum, replace already assigned reviewers with a random reviewer. This option helps prevent "review loops" where only a few authors review an area of code.

Default: 0


If the assigned reviewer has greater percentage authorship of the changed files than this minimum, an extra reviewer will be assigned. This is helpful for files with many authors and one author with majority authorship, making them the default reviewer for those files. Set to 0 to disable.

Default: 0


When using min_authors_of_changed_files or min_percent_authorship_for_extra_reviewer, a small pull request can warrant an extra reviewer if there aren't enough distinct authors of the changed code. However, small pull requests usually don't need more than one reviewer. This option can be used to ensure that an extra reviewer is assigned for pull requests that change at least a minimum of lines of code.

Default: 0


Require a user to be listed in the reviewers section in order to be assigned as a reviewer.

Default: true


Use review requests instead of assignees to assign reviewers to pull requests.

Default: false


A map of maps, with the main keys being the GitHub usernames of users, and the child keys providing application-specific contact information. Example:

    slack: ajones
  bob: {}
  charlie: "Charlie Smith"

When Pull Review sends its notification, it'll notify @alice on GitHub and @ajones on Slack.

Specifically for Slack, using real names instead of usernames (as in the example above for charlie) is recommended since Slack is phasing out support for @username mentions.

If non-GitHub notification handles are not available/required, an empty object can be specified (as it is for bob in the example above). This will notify @bob on GitHub, and will work with the require_notification configuration option.

Currently only Slack user mapping is supported - for other chat networks like HipChat or IRC, Pull Review will mention the GitHub usernames instead.


A list of usernames to never notify. This is useful to exclude machine users and users who are on vacation or otherwise unavailable for reviews.


A map of lists, where the keys are minimatch (glob) patterns, and the lists include the users to assign. Note: order is important. Example:

  - bob

When a file in web/server is found, bob will be assigned before other reviewers.


A map of lists, where the keys are minimatch (glob) patterns, and the lists include the users to assign. Note: order is important. Example:

  - alice

When a file whose path begins with web/ui is found, alice will be assigned if more reviewers are required.


An array of minimatch (glob) patterns that should be filtered out when retrieving files for a pull request. Blacklisted files will not be considered in Git blame processing, in fallback path processing, or in max files per reviewer or max lines per reviewer calculations. Example:

  - web/ui/*.js


An array of pull request labels that are required for pull request review.


An array of pull request labels that are forbidden from pull request review.


An array of channels to use for review notifications. The default channels are chat (the same chat channel that Hubot uses, e.g. Slack) and github (a comment on the pull request).

To disable notifications, use an empty array:

notification_channels: []

Environment variables

  • PULL_REVIEW_GITHUB_TOKEN: GitHub token used to fetch pull request information.
  • PULL_REVIEW_CONFIG_PATH: location of the config file in the pull request repo (default is .pull-review).
  • PULL_REVIEW_CONFIG: Pull Review configuration override in JSON/YAML format.
  • PULL_REVIEW_REQUIRED_ROOMS: whitelist of Hubot chat rooms for Pull Review requests (e.g. dev,ops).

Reviewing again

Sometimes it may be useful to run Pull Review again on a pull request, whether it's because the assigned reviewers are not available to review the PR or because another set of reviewers is necessary. You can run Pull Review again in the following ways:

  • GitHub: /review again
  • Hubot: review ... again
  • CLI: --retry-review or -r
  • API: retryReview: true

When running Pull Review again, current reviewers are un-assigned, and the next best set of reviewers is assigned instead. Keep in mind that if Pull Review runs twice on a pull request, the original reviewers will be assigned again.


Pull Review was partly inspired by mention-bot, however its algorithm is a bit different.

Limits can be set on files per reviewer and lines of code per reviewer. This helps by adding reviewers as needed.


Pull Review supports Node.js 8+.




Made by Ivan Malopinsky.