How to Use the CODEOWNERS File in open-seo for Repository Management

The CODEOWNERS file automatically assigns designated users or teams as reviewers when specific files change, enforcing mandatory approval for critical paths that affect repository governance.

In the open-seo repository, this mechanism protects the review-control plane by ensuring changes to policy-defining files cannot merge without maintainer oversight. This article explains how to configure CODEOWNERS based on the project's actual documentation and governance structure.

---

Why CODEOWNERS Matters in open-seo

The open-seo project maintains strict controls over files that modify how code review itself operates. According to the repository's AGENTS.md and CLAUDE.md documentation, changes to certain paths must receive explicit maintainer review because they alter the rules governing review:

• .greptile/** — automated review rules and configurations
• AGENTS.md — agent behavior and policy documentation
• CLAUDE.md — AI assistant instructions and constraints
• .agents/skills/** — agent skill definitions and enforcement logic
• .github/** — GitHub workflows, issue templates, and settings

Without CODEOWNERS, these files could be modified by any contributor and merged without specialized review, creating a circular dependency risk: someone could change the rules that determine who reviews their changes.

---

How CODEOWNERS Works in open-seo

When properly configured, GitHub performs three automatic actions:

1. Reviewer assignment — When a pull request touches a path listed in CODEOWNERS, GitHub adds the designated owners as reviewers automatically
2. Branch protection enforcement — If "Require review from Code Owners" is enabled, merging is blocked until those owners approve
3. Path-specific control — Different directories can have different owners, enabling fine-grained governance

The enforcement is implemented in coordination with branch protection rules in .github/ settings, not by CODEOWNERS alone.

---

Setting Up CODEOWNERS in open-seo

Follow these steps to implement code owner governance matching the open-seo project's requirements.

Step 1: Create the CODEOWNERS File

Add a file named CODEOWNERS at the repository root or inside .github/:

.github/CODEOWNERS

# or

CODEOWNERS

GitHub recognizes both locations; .github/CODEOWNERS is preferred for organization.

Step 2: Define Owners for Protected Paths

Based on the documentation in AGENTS.md and CLAUDE.md, configure ownership for the review-control files:

# CODEOWNERS — Owners for open-seo review-control plane

# Changes to these files affect who can review what; require maintainer approval

/.greptile/            @every-app/reviewers
/AGENTS.md            @every-app/reviewers
/CLAUDE.md            @every-app/reviewers
/.agents/skills/      @every-app/reviewers
/.github/             @every-app/reviewers

Replace @every-app/reviewers with your actual GitHub username, team handle, or multiple individuals separated by spaces:

# Multiple owners (any one approval satisfies the requirement)

/CLAUDE.md            @alice @bob @every-app/leads

Step 3: Enable Branch Protection

Navigate to Settings > Branches in your GitHub repository and configure protection for your default branch:

• Enable "Require pull request reviews before merging"
• Check "Require review from Code Owners"

This setting transforms the CODEOWNERS file from informational into mandatory — PRs cannot merge until specified owners approve.

Step 4: Maintain Path Coverage

When adding new policy-affecting files or directories, update CODEOWNERS before merging. The /.agents/skills/maintain-greptile-rules/SKILL.md file demonstrates this discipline: skills that enforce rules must themselves be owned.

---

CODEOWNERS Pattern Examples for open-seo

Use these patterns to handle common scenarios in the repository:

Minimal Configuration (Getting Started)

# CODEOWNERS — Essential review-control coverage

/.greptile/           @every-app/reviewers
/AGENTS.md           @every-app/reviewers
/CLAUDE.md           @every-app/reviewers
/.agents/skills/     @every-app/reviewers
/.github/            @every-app/reviewers

Granular Team Assignment

# Different teams for different concerns

/.greptile/           @every-app/automation-team
/.agents/skills/      @every-app/automation-team
/AGENTS.md           @every-app/product-leads
/CLAUDE.md           @every-app/product-leads
/.github/workflows/  @every-app/devops-team

Adding New Protected Directories

# After adding a new governance directory

/security-policies/   @every-app/security-team
/review-configs/      @every-app/reviewers

Fallback Ownership

# Default owner for any file not otherwise covered

*                    @every-app/fallback-maintainers

# Override with specific paths

/CLAUDE.md           @every-app/ai-governance  # Takes precedence over *

---

Key open-seo Files Related to CODEOWNERS

Path	Relevance to CODEOWNERS
AGENTS.md	Documents the requirement: "files that affect how we review code must themselves be reviewed by maintainers"
CLAUDE.md	Reinforces code-owner approval for review-control files; defines constraints on AI-assisted changes
.agents/skills/maintain-greptile-rules/SKILL.md	Demonstrates implementation: a skill that enforces rules must have its own ownership enforcement
.github/ (settings UI)	Where branch protection rules activate "Require review from Code Owners"
CODEOWNERS (to be created)	The central mapping file driving all automatic reviewer assignment

---

Summary

• The CODEOWNERS file in open-seo protects the review-control plane by mandating maintainer approval for policy-affecting files
• Protected paths include .greptile/, AGENTS.md, CLAUDE.md, .agents/skills/, and .github/ as documented in the repository
• Branch protection must enable "Require review from Code Owners" for enforcement; the file alone does not block merges
• Pattern order matters — later lines override earlier ones, with specific paths taking precedence over wildcards
• Maintenance is critical — add new policy files to CODEOWNERS before merging them to preserve governance integrity

---

Frequently Asked Questions

Where should the CODEOWNERS file be placed in open-seo?

GitHub recognizes CODEOWNERS at the repository root, in .github/, or in docs/. For open-seo, use .github/CODEOWNERS to keep repository management files consolidated with other GitHub configurations. The file in .github/ is also slightly higher priority if multiple CODEOWNERS files exist.

Can CODEOWNERS prevent merging without approval?

Not by itself. The CODEOWNERS file only defines who should review. To enforce approval, you must enable "Require review from Code Owners" in branch protection settings. Without this setting, GitHub will suggest owners as reviewers but allow merge without their approval.

What happens if a pull request touches multiple CODEOWNERS paths?

GitHub collects all unique owners from all matching patterns and requests review from each. In open-seo, if a PR modifies both CLAUDE.md and a file in .greptile/, and both list @every-app/reviewers, that team receives one review request. If different paths have different owners, all are added and all must approve (when branch protection requires code owner review).

How do I add CODEOWNERS for a new agent skill I created?

Add the skill's directory path to CODEOWNERS before committing the skill itself. Following the pattern in .agents/skills/maintain-greptile-rules/SKILL.md, insert a line like:

/.agents/skills/your-skill-name/  @every-app/reviewers

This ensures your new skill — which may enforce review rules — cannot be modified without the same oversight it enforces on others.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}