# `labels`

Each scope can define an associated label. The label will be added to a PR automatically when a scope matches.

```toml
[[scopes]]
name = "app"
paths = ["app/**/*"]
labels = ["review/app"]
```

You can also use aliases in the `labels` list to reference predefined label groups.

## How labels are kept up to date

PullApprove keeps its labels in step with the scopes that match as the PR changes:

- **Added** when a scope with that label matches — including on draft PRs, since a label describes the PR (who wrote it, what it touches), not whether it's ready for review.
- **Removed** when no matching scope wants it anymore — for example, after a push that stops touching the scope's paths, or a config change that renames the label.
- **Put back** if a scope starts matching again after PullApprove removed the label.
- **Replaced** by the [`large_scale_change`](../large-scale-change.md) labels if the PR is detected as a large scale change. Scopes aren't matched for a large scale change, so their labels come off.

PullApprove only manages labels it added itself:

- A label that was already on the PR (added by a person or another bot) is never removed, even if it matches a scope's label.
- If someone removes a label PullApprove added, it stays off. PullApprove won't add it back to that PR.
- If someone removes a PullApprove label and later adds it back, it's theirs — PullApprove won't remove it again.

If the config stops applying to a PR entirely (for example, it's retargeted to a branch the config doesn't cover), PullApprove removes the labels it added. If processing fails (for example, a config that can't be loaded), labels are left as they are until it's fixed, so a broken config doesn't strip labels from open PRs.

Labels can be turned off entirely in the repo settings.