{"id":13532839,"url":"https://github.com/imsky/pull-review","last_synced_at":"2025-04-05T23:06:11.505Z","repository":{"id":18261158,"uuid":"83502071","full_name":"imsky/pull-review","owner":"imsky","description":":white_check_mark: Assign pull request reviewers intelligently.","archived":false,"fork":false,"pushed_at":"2023-03-02T12:20:06.000Z","size":1058,"stargazers_count":205,"open_issues_count":34,"forks_count":17,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-14T10:50:44.955Z","etag":null,"topics":["github","hacktoberfest","hubot","pull-requests","review","slack"],"latest_commit_sha":null,"homepage":"https://pull-review.herokuapp.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imsky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-03-01T02:27:13.000Z","updated_at":"2024-04-14T06:17:56.000Z","dependencies_parsed_at":"2023-07-25T18:46:28.083Z","dependency_job_id":null,"html_url":"https://github.com/imsky/pull-review","commit_stats":{"total_commits":292,"total_committers":4,"mean_commits":73.0,"dds":0.09246575342465757,"last_synced_commit":"e6e2bcdf5390253fda44e427b78464087f75c76b"},"previous_names":["imsky/hubot-review","imsky/hubot-pull-review"],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsky%2Fpull-review","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsky%2Fpull-review/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsky%2Fpull-review/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imsky%2Fpull-review/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imsky","download_url":"https://codeload.github.com/imsky/pull-review/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246944391,"owners_count":20858773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","hacktoberfest","hubot","pull-requests","review","slack"],"created_at":"2024-08-01T07:01:14.180Z","updated_at":"2025-04-05T23:06:11.482Z","avatar_url":"https://github.com/imsky.png","language":"JavaScript","readme":"# Pull Review\n\n[![coverage report](https://gitlab.com/imsky/pull-review/badges/master/coverage.svg)](https://gitlab.com/imsky/pull-review/commits/master) [![pipeline status](https://gitlab.com/imsky/pull-review/badges/master/pipeline.svg)](https://gitlab.com/imsky/pull-review/commits/master) [![npm](https://img.shields.io/npm/v/pull-review.svg)](https://www.npmjs.com/package/pull-review) [![license](https://img.shields.io/github/license/imsky/pull-review.svg)](https://github.com/imsky/pull-review/blob/master/LICENSE)\n\n![Pull Review](https://imsky.github.io/pull-review/pull-review-github-header.png)\n\n**Pull Review** assigns pull request reviewers [intelligently](#algorithm).\n\nPull 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](#configuration).\n\nYou can use Pull Review through [GitHub comments](#github), from chat rooms in Slack/HipChat/etc. using [Hubot](#hubot), on the [command line](#cli), via [API](#api), or as a [Docker image](#docker).\n\n## Installation\n\n```\nnpm install pull-review\n```\n\n[![Deploy Pull Review to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/imsky/pull-review)\n\n## Usage\n\nFirst, add a `.pull-review` configuration file in your repository:\n\n```yaml\nversion: 1\n\nreviewers:\n  your_github_username: {}\n```\n\nIn order to use Pull Review as a Hubot plugin or in server mode, you'll need a [GitHub token](https://github.com/settings/tokens). The token must have `repo`, `public_repo`, `read:user`, and `read:org` scopes.\n\nFor details on configuration options, check out the [configuration](#configuration) section.\n\n### GitHub\n\n![Pull Review used with GitHub](https://imsky.github.io/pull-review/pull-review-github.png)\n\n* In your GitHub repository, go to **Settings**→**Webhooks**\n* Click **Add webhook**\n* Set **Payload URL** to the Pull Review server URL (\u003chttps://pull-review.herokuapp.com\u003e)\n* Set **Content type** to `application/json`\n* Choose **Let me select individual events**\n* Pick the **Issue comment** event\n* Click **Add webhook**\n\nTo assign reviewers on a pull request, post `/review`. To [run Pull Review again](#reviewing-again) post `/review again`.\n\n\u003e The public Pull Review server limits some configuration options. However, you can [run your own server](#server).\n\n### Hubot\n\n![Pull Review used with Hubot](https://imsky.github.io/pull-review/pull-review-hubot.png)\n\nAdd `pull-review` to your `external-scripts.json`:\n\n```json\n[\n  \"pull-review\"\n]\n```\n\nEnsure [environment variables](#environment-variables) are set correctly.\n\nYou can request review assignments like this:\n\n```text\nreview https://github.com/imsky/pull-review/pull/1\n```\n\nYou can [run Pull Review again](#reviewing-again) on a pull request like this:\n\n```text\nreview https://github.com/imsky/pull-review/pull/1 again\n```\n\nTo notify users on Slack, configuration must include a [reviewers](#reviewers) section.\n\nPull Review also adds a pull request preview, for private and public repos.\n\n### CLI\n\n```bash\nnpm install --global pull-review\n\npull-review https://github.com/imsky/pull-review/pull/1\n\npull-review --help\n\n  Usage: pull-review [options] \u003cpull request URL\u003e\n\n\n  Options:\n\n    -V, --version                     output the version number\n    -r, --retry-review                Retry review\n    -d, --dry-run                     Do not assign or notify reviewers\n    -t, --github-token \u003cgithubToken\u003e  GitHub token to use\n    -c, --config-path \u003cconfigPath\u003e    Pull Review configuration path in repo\n    -h, --help                        output usage information\n```\n\n### API\n\n```js\nvar PullReview = require('pull-review');\n\nPullReview({\n  pullRequestURL: 'https://github.com/imsky/pull-review/pull/1',\n\n  // run Pull Review on a pull request, unassigning current reviewers first\n  retryReview: true,\n\n  // run Pull Review on a pull request, but do not assign or notify reviewers\n  dryRun: true,\n\n  // run Pull Review with a specific GitHub token\n  githubToken: 'PULL_REVIEW_GITHUB_TOKEN'\n\n  // run Pull Review with a custom Pull Review configuration\n  config: {version: 1},\n\n  // specify a different repo location for the Pull Review configuration\n  pullReviewConfigPath: 'config/.pull-review'\n});\n```\n\n### Docker\n\nThe Docker image can be used in [CLI](#cli) mode or in [server](#server) mode.\n\n```bash\n# get the Pull Review image\ndocker pull ghcr.io/imsky/pull-review\n\n# run Pull Review on a pull request\ndocker run -it -e PULL_REVIEW_GITHUB_TOKEN ghcr.io/imsky/pull-review https://github.com/imsky/pull-review/pull/1\n\n# run Pull Review with a specific GitHub token\ndocker run -it ghcr.io/imsky/pull-review https://github.com/imsky/pull-review/pull/1 --github-token PULL_REVIEW_GITHUB_TOKEN\n```\n\n### Server\n\nYou can run your own Pull Review server [on Heroku](https://heroku.com/deploy?template=https://github.com/imsky/pull-review) or another host.\n\nEnsure [environment variables](#environment-variables) are set correctly.\n\nStart the server with `npm start` or by [running `pull-review`](#cli) with no arguments.\n\nThe port is 8080 by default, but can be changed using the `PORT` environment variable.\n\n## Configuration\n\nConfiguration for Pull Review is a YAML/JSON file named `.pull-review` at the root of the repo.\n\nCheck out [.pull-review](.pull-review) for a documented example of a config file.\n\n#### max_files\n\nMaximum number of files to evaluate in order to assign reviewers. Set to 0 for no maximum.\n\nDefault: 5\n\n#### min_reviewers\n\nMinimum number of reviewers to assign.\n\nDefault: 1\n\n#### max_reviewers\n\nMaximum number of reviewers to assign.\n\nDefault: 2\n\n#### max_files_per_reviewer\n\nMaximum 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](#max_reviewers). Set to 0 for no maximum.\n\nDefault: 0\n\n#### max_lines_per_reviewer\n\nMaximum 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](#max_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.\n\nDefault: 0\n\n#### assign_min_reviewers_randomly\n\nIf the [minimum number of reviewers](#min_reviewers) isn't found, assign reviewers using [path fallbacks](review_path_fallbacks) and/or at random.\n\nDefault: true\n\n#### min_authors_of_changed_files\n\nIf 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.\n\nDefault: 0\n\n#### min_percent_authorship_for_extra_reviewer\n\nIf 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.\n\nDefault: 0\n\n#### min_lines_changed_for_extra_reviewer\n\nWhen using [min_authors_of_changed_files](#min_authors_of_changed_files) or [min_percent_authorship_for_extra_reviewer](#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.\n\nDefault: 0\n\n#### require_notification\n\nRequire a user to be listed in the [reviewers](#reviewers) section in order to be assigned as a reviewer.\n\nDefault: true\n\n#### use_review_requests\n\nUse [review requests](https://help.github.com/articles/about-pull-request-reviews/) instead of [assignees](https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users/) to assign reviewers to pull requests.\n\nDefault: false\n\n#### reviewers\n\nA map of maps, with the main keys being the GitHub usernames of users, and the child keys providing application-specific contact information. Example:\n\n```yaml\nreviewers:\n  alice:\n    slack: ajones\n  bob: {}\n  charlie: \"Charlie Smith\"\n```\n\nWhen Pull Review sends its notification, it'll notify `@alice` on GitHub and `@ajones` on Slack.\n\nSpecifically 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](https://api.slack.com/changelog/2017-09-the-one-about-usernames).\n\nIf 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`](#require_notification) configuration option.\n\nCurrently only Slack user mapping is supported - for other chat networks like HipChat or IRC, Pull Review will mention the GitHub usernames instead.\n\n#### review_blacklist\n\nA list of usernames to never notify. This is useful to exclude machine users and users who are on vacation or otherwise unavailable for reviews.\n\n#### review_path_assignments\n\nA map of lists, where the keys are [minimatch](https://github.com/isaacs/minimatch) (glob) patterns, and the lists include the users to assign. **Note:** order is important. Example:\n\n\n```yaml\nreview_path_assignments:\n  web/server/**:\n  - bob\n```\n\nWhen a file in `web/server` is found, `bob` will be assigned before other reviewers.\n\n#### review_path_fallbacks\n\nA map of lists, where the keys are [minimatch](https://github.com/isaacs/minimatch) (glob) patterns, and the lists include the users to assign. **Note:** order is important. Example:\n\n```yaml\nreview_path_fallbacks:\n  web/ui/**:\n  - alice\n```\n\nWhen a file whose path begins with `web/ui` is found, `alice` will be assigned if more reviewers are required.\n\n#### file_blacklist\n\nAn array of [minimatch](https://github.com/isaacs/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](#review_path_fallbacks), or in [max files per reviewer](#max_files_per_reviewer) or [max lines per reviewer](#max_lines_per_reviewer) calculations. Example:\n\n```yaml\nfile_blacklist:\n  - web/ui/*.js\n```\n\n#### label_whitelist\n\nAn array of pull request labels that are required for pull request review.\n\n#### label_blacklist\n\nAn array of pull request labels that are forbidden from pull request review.\n\n#### notification_channels\n\nAn 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).\n\nTo disable notifications, use an empty array:\n\n```yaml\nnotification_channels: []\n```\n\n### Environment variables\n\n* `PULL_REVIEW_GITHUB_TOKEN`: GitHub token used to fetch pull request information.\n* `PULL_REVIEW_CONFIG_PATH`: location of the config file in the pull request repo (default is `.pull-review`).\n* `PULL_REVIEW_CONFIG`: Pull Review configuration override in JSON/YAML format.\n* `PULL_REVIEW_REQUIRED_ROOMS`: whitelist of Hubot chat rooms for Pull Review requests (e.g. `dev,ops`).\n\n## Reviewing again\n\nSometimes 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:\n\n* [GitHub](#github): `/review again`\n* [Hubot](#hubot): `review ... again`\n* [CLI](#cli): `--retry-review` or `-r`\n* [API](#api): `retryReview: true`\n\nWhen 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.\n\n## Algorithm\n\nPull Review was partly inspired by [mention-bot](https://github.com/facebook/mention-bot), however its algorithm is a bit different.\n\n* Get all modified files for a pull request and take the [top files](#max_files) with most changes\n* Get information on which author changed what lines in these files using [Git blame](https://git-scm.com/docs/git-blame) data, filtering out older data\n* Assign [authors who have precedence for particular paths](#review_path_assignments)\n* Assign authors who have made the most changes in the top modified files\n* If there are [not enough reviewers](#min_reviewers), assign more reviewers from [path fallback rules](#review_path_fallbacks)\n* If there are still not enough reviewers, assign at random from a list of [all reviewers](#reviewers)\n\nLimits can be set on [files per reviewer](#max_files_per_reviewer) and [lines of code per reviewer](#max_lines_per_reviewer). This helps by adding reviewers as needed.\n\n## Support\n\nPull Review supports Node.js 8+.\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT)\n\n## Credits\n\nMade by [Ivan Malopinsky](http://imsky.co).\n","funding_links":[],"categories":["JavaScript","开发流程工具","Code Reviews"],"sub_categories":["Code reviews"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimsky%2Fpull-review","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimsky%2Fpull-review","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimsky%2Fpull-review/lists"}