Skip to main content

Code Ownership with CODEOWNERS

What is a CODEOWNERS file?​

The CODEOWNERS file is a way to define individuals or teams responsible for specific files or directories in a GitHub repository. It helps automate the code review process by automatically requesting reviews from designated owners when certain files are changed.

Why use a CODEOWNERS file?​

  • Maintain code quality: Ensure that changes to critical or complex parts of the code are reviewed by the right experts.
  • Enforce responsibility: Clarify who owns and maintains certain files or folders.
  • Simplify reviews: Automate reviewer assignment in pull requests.
  • Improve collaboration: Avoid confusion over who should review or approve changes.

Where to place CODEOWNERS​

  • Add the CODEOWNERS file at the root of your repository (e.g., /CODEOWNERS).
  • It can also be placed under the .github/ or docs/ folders.
  • GitHub supports these locations and prioritizes rules in this order:
    1. .github/CODEOWNERS
    2. docs/CODEOWNERS
    3. CODEOWNERS at repo root

Syntax and Usage​

The general syntax for the CODEOWNERS file:

# File or path pattern  @username(s) or @team(s)
  • Specify paths relative to the root of the repository.
  • Use @username for individual owners.
  • Use @org/team-name for GitHub teams.
  • Wildcards (*) and directory matches with trailing slashes (/) are supported.

Example: Assigning Owners​

# Owner for a single file
lib/tokens.dart @alice

# Owners (multiple) for a single file
lib/tokens.dart @alice @bob

# Owner for a directory and all its files
lib/components/ @frontend-team

# Owner for all files in the repository
* @alice

How It Works in GitHub​

  • When a pull request (PR) modifies files matched in CODEOWNERS, GitHub automatically requests a review from the specified owners.
  • Branch protection rules can require approval from code owners before allowing a PR to be merged.
  • This helps ensure that code changes are reviewed by the appropriate people.

When to Use CODEOWNERS​

  • Protect critical files that require expert review.
  • Assign ownership to key areas or sensitive parts of the codebase.
  • Maintain clear responsibility for different modules or features.
  • In projects with multiple maintainers or teams collaborating on different parts.

Best Practices​

  • Keep CODEOWNERS up-to-date as the team or codebase changes.
  • Use GitHub teams (e.g., @org/team-name) for better scalability and easier management.
  • Combine CODEOWNERS with branch protection rules for enforcement.
  • Avoid overly broad ownership that can cause bottlenecks.
  • Communicate ownership responsibilities clearly to the team.