# `aliases`

Reviewer aliases can be defined at the root of the `CODEREVIEW.toml` file. These aliases can be used anywhere a list of strings is expected, such as `reviewers`, `alternates`, `authors`, `cc`, or `labels`.

To reference an alias, use the `$` prefix.

```toml
[aliases]
devs = ["dev1", "dev2", "dev3", "dev4"]

[[scopes]]
name = "app"
reviewers = ["$devs"]
```

## Nested aliases

Aliases can reference other aliases, allowing you to build complex reviewer groups:

```toml
[aliases]
backend = ["alice", "bob"]
frontend = ["carol", "dave"]
qa = ["eve"]
all_devs = ["$backend", "$frontend"]
everyone = ["$all_devs", "$qa", "frank"]

[[scopes]]
name = "app"
reviewers = ["$everyone"]
# Expands to: ["alice", "bob", "carol", "dave", "eve", "frank"]
```

PullApprove will raise an error if it detects circular references in aliases (e.g., if alias A references B, and B references A). It also raises an error if a `$alias` reference has no matching definition, so a typo surfaces loudly instead of silently dropping the reviewer or path. These checks help catch configuration mistakes early.

To manage `aliases` at scale across your organization, you can make use of [templates](../admin/templates.md) to sync the same `aliases` to multiple repos.

## FAQs

### What about GitHub Teams?

If a reviewer group already exists as a GitHub Team or GitLab group, you can reference it directly with the `@` prefix instead of maintaining an alias — see [teams](../teams.md). Aliases are for review-specific groupings that don't correspond to a real team, or when you want the membership visible in the config itself.

The term `aliases` was inspired by [Kubernetes OWNERS](https://www.kubernetes.dev/docs/guide/owners/#owners_aliases), which uses the same concept.