# `request`

Once a change is opened as a pull request, PullApprove will automatically `request` reviewers for each scope that matches the files in the PR.

```toml
[[scopes]]
name = "app"
reviewers = ["dev1", "dev2"]
request = 1
```

Behavior:

- The default is `request = 0`. If omitted, no reviewers are requested automatically.
- Reviewers are chosen at random. The order is drawn once per pull request, using the PR number as a seed. It holds as long as the scope's `reviewers` are unchanged, so when someone drops out, the next name in that order is asked. Editing `reviewers`, naming one of them in `alternates`, or a change in a team's membership draws a new order.
- `request` is how many people the scope asks at a time. [`require`](require.md) is how many approvals it needs. If `require` is greater than `request`, another person is asked as each approval comes in, until `require` approvals are in.
- A scope only asks for as many people as it is still short. See [Who already counts](#who-already-counts).
- Wildcard (`*`) reviewers are never auto-requested.
- With mixed reviewers like `reviewers = ["alice", "bob", "*"]`, only alice and bob will be auto-requested.
- Someone in both `reviewers` and `alternates` might not be requested. See [Someone in both lists](alternates.md#someone-in-both-lists).
- Reviewers whose GitHub status is set to **Busy** are skipped while someone else in the scope is available. See [Busy reviewers](#busy-reviewers).

## Who already counts

A scope asks for `request` people, minus anyone in its `reviewers` or [`alternates`](alternates.md) who already:

- was requested by hand, before or after PullApprove ran
- was requested by a scope handled before this one (see [Order matters](#order-matters))
- was requested by PullApprove on an earlier pass and has not reviewed yet
- has reviewed. A comment or a changes-requested review counts the same as an open request. An approval counts toward `require`.

A request PullApprove sends counts from the moment it is sent, so the person shows as pending even before the git host reports the request back.

When `*` is one of the scope's `reviewers`, including in a mixed list like `["alice", "bob", "*"]`, everybody on the pull request counts. Otherwise nobody outside the scope's `reviewers` and `alternates` counts, so two scopes with no reviewers in common each ask for their own people no matter how many requests are already on the pull request.

## Order matters

Scopes are handled top to bottom in the order they are written. When a pull request touches files covered by more than one `CODEREVIEW.toml`, the config files are handled in path order, with the root one first.

Put the specific scope first, and give the broad scope below it [`ownership = "append"`](ownership.md) so both apply to the same files:

```toml
[[scopes]]
name = "codeowners"
paths = ["app/**"]
reviewers = ["ali", "bo", "cam"]
request = 2

[[scopes]]
name = "minimum-reviewers"
ownership = "append"
paths = ["**/*"]
reviewers = ["ali", "bo", "cam", "dee", "eze", "fen"]
request = 2
```

`codeowners` asks two of its three people. `minimum-reviewers` counts those two, because they are also in its `reviewers`, and asks nobody.

If `minimum-reviewers` were written first, it would ask any two of its six people. `codeowners` would then ask only for as many as it is still short: two if neither of those two is a codeowner, one if one is, none if both are. Either way two codeowners are asked, but the pull request can end up with four people asked instead of two.

## Removed requests

PullApprove never withdraws a review request. People do. No matter who removes it, the scope is one short and the next person in its order is asked.

This applies to requests people made by hand, not only to ones PullApprove sent.

The removed person is never auto-requested again on that pull request. They also stop appearing in the pull request's next steps and in the status comment's pending column. The reviewer list in the review workspace still shows them. If you want a specific person instead of the next in line, request them by hand. A person requested by hand counts, so PullApprove asks nobody else.

PullApprove re-reads the pull request from GitHub or GitLab before every pass, so it works from the host's current reviewer list rather than the last event it received. If a request PullApprove sent is no longer on the pull request, that person has not reviewed or commented, and the pull request has changed since the request went out, PullApprove treats the request as removed: the place frees for the next person in the scope's order, and the person whose request vanished is not asked again.

## Busy reviewers

GitHub lets people flag limited availability by setting their status to "Busy". PullApprove honors that flag when it picks who to request: a busy reviewer is passed over for the next name in the scope's random order. If everyone eligible is busy, the request still goes out, because a pull request with no reviewer is worse than a request to a busy one.

The busy check only affects automatic requests. Busy reviewers can still approve, and requests made by hand are untouched. The people who were skipped are recorded on the review request event in the pull request timeline.

Statuses limited to your organization count too, so a status set by an integration (for example a Slack sync) works without any extra setup. The check can be turned off per repository in the repo settings ("Skip busy reviewers when requesting").