Codeowners

Codeowners is a fast, Rust-based CLI for generating and validating GitHub CODEOWNERS files in large repositories.

Note: For Ruby applications, it's usually easier to use codeowners-rs via the code_ownership gem.

🚀 Quick Start: Generate & Validate

The most common workflow is to generate and validate in one step:

codeowners gv

• Generates a fresh CODEOWNERS file (default: .github/CODEOWNERS)
• Validates ownership and that the file is up to date
• Exits non-zero and prints detailed errors if validation fails

Table of Contents

• Quick Start: Generate & Validate
• Installation
• Getting Started
• Declaring Ownership
  • Directory-Based Ownership
  • File Annotation
  • Package-Based Ownership
  • Glob-Based Ownership
  • JavaScript Package Ownership
• CLI Reference
  • Global Flags
  • Commands
  • Examples
• Configuration
• Cache
• Validation
• Library Usage
• Development

Installation

You can run codeowners without installing a platform-specific binary by using DotSlash, or install from source with Cargo.

Option A: DotSlash (recommended)

1. Install DotSlash: see https://dotslash-cli.com/docs/installation/
2. Download the latest DotSlash text file from a release, for example https://github.com/rubyatscale/codeowners-rs/releases.
3. Execute the downloaded file with DotSlash; it will fetch and run the correct binary.

Release archives after v0.5.0 also hold a licenses directory next to the codeowners binary. It has the license notices that the dependencies listed in dev/license-notices require redistributions of the binary to include.

Option B: From source with Cargo

Requires Rust toolchain.

cargo install --git https://github.com/rubyatscale/codeowners-rs codeowners

Getting Started

1. Configure Ownership
   Create a config/code_ownership.yml file. Example:

   owned_globs:
     - '{app,components,config,frontend,lib,packs,spec}/**/*.{rb,rake,js,jsx,ts,tsx}'
   js_package_paths: []
   unowned_globs:
     - db/**/*
     - app/services/some_file1.rb
     - frontend/javascripts/**/__generated__/**/*

2. Declare Teams
   Example: config/teams/operations.yml

   name: Operations
   github:
     team: '@my-org/operations-team'

3. Run the Main Workflow

   codeowners gv

Declaring Ownership

You can declare code ownership in several ways:

1. Directory-Based Ownership

Add a .codeowner file to a directory with the team name as its contents:

TeamName

2. File Annotation

Add an annotation at the top of a file:

# @team MyTeam

// @team MyTeam

<!-- @team MyTeam -->

<%# @team: Foo %>

3. Package-Based Ownership

In package.yml (for Ruby Packwerk):

owner: TeamName

4. Glob-Based Ownership

In your team's YML:

owned_globs:
  - app/services/my_team/**/*
unowned_globs:
  - app/services/my_team/legacy/*

unowned_globs "subtracts" from owned_globs

5. JavaScript Package Ownership

In package.json:

{
  "metadata": {
    "owner": "My Team"
  }
}

Configure search paths in code_ownership.yml:

js_package_paths:
  - frontend/javascripts/packages/*

CLI Reference

Global Flags

• --codeowners-file-path <path>: Path for the CODEOWNERS file. Default: ./.github/CODEOWNERS
• --config-path <path>: Path to code_ownership.yml. Default: ./config/code_ownership.yml
• --project-root <path>: Project root. Default: .
• --no-cache: Disable on-disk caching (useful in CI)
• -V, --version, -h, --help

Commands

• generate (g): Generate the CODEOWNERS file and write it to --codeowners-file-path.
  • Flags: --skip-stage, -s to avoid git add after writing
• validate (v): Validate the CODEOWNERS file and configuration.
• generate-and-validate (gv): Run generate then validate.
  • Flags: --skip-stage, -s
• for-file <path> (f): Print the owner of a file.
  • Flags: --from-codeowners to resolve using only the CODEOWNERS rules
• for-team <name> (t): Print ownership report for a team.
• delete-cache (d): Delete the persisted cache.

Examples

Find the owner of a file

codeowners for-file path/to/file.rb

Ownership report for a team

codeowners for-team Payroll

Generate but do not stage the file

codeowners generate --skip-stage

Run without using the cache

codeowners gv --no-cache

Configuration

config/code_ownership.yml keys and defaults:

• owned_globs (required): Glob patterns that must be owned.
• ruby_package_paths (default: ['packs/**/*', 'components/**'])
• js_package_paths / javascript_package_paths (default: ['frontend/**/*'])
• team_file_glob (default: ['config/teams/**/*.yml'])
• unowned_globs (default: ['frontend/**/node_modules/**/*', 'frontend/**/__generated__/**/*'])
• vendored_gems_path (default: 'vendored/')
• cache_directory (default: 'tmp/cache/codeowners')
• ignore_dirs (default includes: .git, node_modules, tmp, etc.)
• executable_name (default: 'codeowners'): Customize the command name shown in validation error messages. Useful when using codeowners-rs via wrappers like the code_ownership Ruby gem.
• yaml_max_nodes (default: 20000): The most YAML nodes (mappings, sequences and scalars) allowed in one team file or package.yml. A file over it, or over the limits on total scalar bytes and anchor copies that grow with it, fails with a budget breached error and a hint to raise this key in the config file in use. Raise it if a large team file hits the limit; real files have at most a few thousand nodes. It does not apply to the config file itself. Raising it also raises how much memory a single file can take: a file crafted to waste memory can make codeowners use about 280 MB more at the default and about 700 MB more at 50,000, measured on macOS, while ordinary files add almost nothing. Separately, any of these files, or the config, fails if it nests more than 16 levels deep, counting the top level. That limit can't be raised.

Example configuration with custom executable name:

owned_globs:
  - '{app,components,config,frontend,lib,packs,spec}/**/*.{rb,rake,js,jsx,ts,tsx}'
executable_name: 'bin/codeownership'  # For Ruby gem wrapper

See examples in tests/fixtures/**/config/ for reference setups.

Cache

By default, cache is stored under tmp/cache/codeowners relative to the project root. This speeds up repeated runs.

• Disable cache for a run: add the global flag --no-cache
• Clear all cache: codeowners delete-cache

Validation

codeowners validate (or codeowners gv) ensures:

1. Only one mechanism defines ownership for any file.
2. All referenced teams are valid.
3. All files in owned_globs are owned, unless matched by unowned_globs.
4. The generated CODEOWNERS file is up to date.

Exit status is non-zero on errors.

Library Usage

Import public APIs from codeowners::runner::*.

use codeowners::runner::{RunConfig, for_file, teams_for_files_from_codeowners};

fn main() {
    let run_config = RunConfig {
        project_root: std::path::PathBuf::from("."),
        codeowners_file_path: Some(std::path::PathBuf::from(".github/CODEOWNERS")), // optional, if None provided, will be resolved from config/env
        config_path: std::path::PathBuf::from("config/code_ownership.yml"),
        no_cache: true, // set false to enable on-disk caching
        executable_name: None,
    };

    // Find owner for a single file using the optimized path (not just CODEOWNERS)
    let result = for_file(&run_config, "app/models/user.rb", false);
    for msg in result.info_messages { println!("{}", msg); }
    for err in result.io_errors { eprintln!("io: {}", err); }
    for err in result.validation_errors { eprintln!("validation: {}", err); }

    // Map multiple files to teams using CODEOWNERS rules only
    let files = vec![
        "app/models/user.rb".to_string(),
        "config/teams/payroll.yml".to_string(),
    ];
    match teams_for_files_from_codeowners(&run_config, &files) {
        Ok(map) => println!("{:?}", map),
        Err(e) => eprintln!("error: {}", e),
    }
}

Development

• Written in Rust for speed and reliability.

• To build locally, install Rust:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Please update CHANGELOG.md and this README.md when making changes.

Module layout

• src/runner.rs: public façade re-exporting the API and types.
• src/runner/api.rs: externally available functions used by the CLI and other crates.
• src/runner/types.rs: RunConfig, RunResult, and runner Error.
• src/ownership/: all ownership logic (parsing, mapping, validation, generation).
• src/ownership/codeowners_query.rs: CODEOWNERS-only queries consumed by the façade.