requirecodeowners

A GitHub Action and CLI tool that ensures directories have CODEOWNERS coverage.

Why?

As codebases grow, it's easy to add new directories without updating CODEOWNERS. This tool catches those gaps in CI, ensuring every important directory has clear ownership.

Quick Start

1. Create .requirecodeowners.yml in your repository:

directories:
  - path: services
    level: 1    # Check each subdirectory of services/
  - path: libs  # Check libs/ itself (level: 0 is default)

2. Add the GitHub Action:

- uses: kpurdon/requirecodeowners@v1

That's it! The action will fail if any configured directories lack CODEOWNERS entries.

Configuration

Match mode

Controls how CODEOWNERS coverage is checked for each directory:

Mode	Behavior
exact (default)	Directory must have its own CODEOWNERS rule. Inheritance from a parent rule is not sufficient.
coverage	Directory only needs to be covered by any CODEOWNERS rule, including inherited parent rules.

directories:
  - path: services
    level: 1
    # Default: each services/* must have its own CODEOWNERS entry
  - path: internal
    level: 1
    match: coverage  # Opt out: parent coverage is acceptable

For example, if CODEOWNERS contains /apps/ @team-apps, a subdirectory apps/my-service/ is covered by inheritance. With the default exact mode, this would fail because apps/my-service/ lacks its own entry. With coverage mode, it would pass.

Level explained

Level	Behavior	Example
0 (default)	Check the directory itself	libs/ must have an entry
1	Check immediate subdirectories	Each services/*/ must have an entry
2	Check two levels deep	Each services/*/*/ must have an entry

Glob patterns

Paths support glob patterns using *:

directories:
  - path: applications/*/services
    level: 1

This matches applications/a/services, applications/b/services, etc., and checks that each of their subdirectories has CODEOWNERS coverage.

Full example

directories:
  - path: services
    level: 1           # services/auth/, services/api/, etc. must each have an exact CODEOWNERS entry
  - path: libs
    level: 2           # libs/go/utils/, libs/js/common/, etc.
  - path: internal
    level: 1
    match: coverage    # parent CODEOWNERS coverage is acceptable
  - path: docs         # docs/ itself (level defaults to 0)

GitHub Action

Basic usage

name: Require CODEOWNERS

on:
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kpurdon/requirecodeowners@v1

Inputs

Name	Required	Default	Description
config	No	.requirecodeowners.yml	Path to config file
codeowners-path	No	auto-detected	Path to CODEOWNERS file
version	No	latest	CLI version to use

Output

When directories are missing CODEOWNERS coverage, you'll see clear error messages:

  ✗ services/new-api
    Not covered by CODEOWNERS. Add: /services/new-api/ @your-team

✗ 1 directory failed CODEOWNERS check

GitHub Actions also displays a summary table for easy scanning.

CLI Usage

Install from releases or use go install:

go install github.com/kpurdon/requirecodeowners@latest

Run in any repository with a .requirecodeowners.yml:

requirecodeowners
requirecodeowners --config path/to/config.yml
requirecodeowners --codeowners-path .github/CODEOWNERS

Example Repository

See kpurdon/requirecodeowners-example for a complete working example demonstrating various failure modes.