Code Approvers

Code Approvers are a list of GitHub usernames or teams that can review and accept pull request changes to a directory or file.

You can enable Code Approvers for a directory by adding a .vercel.approvers file to that directory in your codebase. For example, this .vercel.approvers file defines the GitHub team vercel/ui-team as an approver for the packages/design directory:

@vercel/ui-team

When a team is declared as an approver, all members of that team will be able to approve changes to the directory or file and at least one member of the team must approve the changes.

Code Approvals by the correct owners are enforced through a GitHub check added by the Vercel GitHub App.

When a pull request is opened, the GitHub App will check if the pull request contains changes to a directory or file that has Code Approvers defined.

If no Code Approvers are defined for the changes then the check will pass. Otherwise, the check will fail until the correct Code Approvers have approved the changes.

Code Approvers are inherited from parent directories. If a directory does not have a .vercel.approvers file, then the approvers from the parent directory will be used. Furthermore, even if a directory does have a .vercel.approvers file, then the approvers from a parent directory with a .vercel.approvers file can also approve the changed files. This structure allows the most specific approver to review most of the code, but allows other approvers who have broader context and approval power to still review and approve the code when appropriate.

For example, the following .vercel.approvers file that's declared at the root of the codebase allows users elmo and oscar to approve changes to the packages directory as well.

@elmo
@oscar

When a pull request is opened, the Vercel GitHub App will select the approvers for the changed files. .vercel.approvers files allow extensive definitions of file mappings to possible approvers. In many cases, there will be multiple approvers for the same changed file. The Vercel GitHub app selects the best reviewers for the pull request based on affinity of .vercel.approvers definitions and overall coverage of the changed files.

You can override the reviewer selection by specifying owners directly on the pull request description using:

[vercel:approver:@owner1]
[vercel:approver:@owner2]

The owners you specify must be valid approvers for the changed files in the pull request. Otherwise, Code Owners still requires approvals from the necessary owners.

Modifiers enhance the behavior of Code Approvers for individual users and teams. The available modifiers are: silent, notify, required, and optional.

A modifier doesn't affect the owner's ability to approve a pull request. However, it will affect how the approver is notified about the pull request and whether they are a blocking approver.

# Syntax for modifiers
# Approver with no modifier
@owner1
# Approver with modifier
@owner2:modifier

The user or team is never requested for review. If the user is a non-silent approver in another .vercel.approvers file that is closer to the changed files in the directory structure, then they can still be requested for review.

@owner:silent

The user or team is always notified through a comment on the pull request. This can be useful for teams that want to be notified on every pull request. Vercel will still rotate the selection of team members as the reviewer. This helps avoid the bystander effect in code reviews when teams are tagged instead of individuals.

# The team is always notified.
@vercel/my-team:notify

This user or team is always notified (through a comment) and is a required approver on the pull request. required reviews will block PR checks and do not respect ownership inheritance in the file hierarchy.

# Always notifed and are required reviewers.
# The check won't pass until both `owner1` and `owner2` approve.
@owner1:required
@owner2:required

When you specify a team as a required reviewer only one member of that team is required to approve.

# The team is notifed and are required reviewers.
# The check won't pass until one member of the team approves.
@vercel/my-team:required

The user or team is never requested for review. They are ignored as owners when computing review requirements. The owner can still approve files they have coverage over, including those that have other owners.

This is useful to grant a high level user or team authority over a large scope of the codebase. Any files that only have optional owners will not require approvals. But the optional owner will still have approval rights over their coverage.

@owner:optional

The .vercel.approvers file supports specifying files with a limited set of glob patterns:

• Directory
• Current Directory
• Globstar

The patterns are case-insensitive.

The default empty pattern represents ownership of the current directory and all subdirectories.

# Matches all files in the current directory and all subdirectories.
@owner

A pattern that matches a file or set of files in the current directory.

# Matches the single `package.json` file in the current directory only.
package.json @package-owner
 
# Matches all javascript files in the current directory only.
*.js @js-owner

The globstar pattern begins with **/. And represents ownership of files matching the glob in the current directory and its subdirectories.

# Matches all `package.json` files in the current directory and its subdirectories.
**/package.json @package-owner
 
# Matches all javascript files in the current directory and its subdirectories.
**/*.js @js-owner

Code Owners files are meant to encourage distributed ownership definitions across a codebase. Thus, the globstar **/ and / can only be used at the start of a pattern. They cannot be used in the middle of a pattern to enumerate subdirectories.

For example, the following patterns are not allowed:

# Instead add a `.vercel.approvers` file in the `src` directory.
src/**/*.js @js-owner
 
# Instead add a `.vercel.approvers` file in the `src/pages` directory.
src/pages/index.js @js-owner

If you would like to allow a certain directory or file to be approved by anyone, you can use the wildcard owner *. This is useful for files that are not owned by a specific team or individual. The wildcard owner cannot be used with modifiers.

# Changes to the `pnpm-lock.yaml` file in the current directory can be approved by anyone.
pnpm-lock.yaml *
 
# Changes to any README in the current directory or its subdirectories can be approved by anyone.
**/readme.md *