SPEC v1 Status: stable. You missed the memo.

Code ownership has a new format.

While you were resolving merge conflicts in CODEOWNERS, ownership moved into small owners.yaml files next to the code. One written spec, one resolver, and the same answer for a terminal, a review bot, or the agent that opened fourteen pull requests over lunch.

Catch up on the spec (it has RFC 2119 keywords)
$ uvx owners-yaml who src/that/file.py
No signup. No dashboard. No AI at runtime, it just reads YAML. Plenty of AI in the commit history, and we are not going to pretend otherwise.
zsh, the obligatory hero terminal
# billing/owners.yaml
version: 1
owners: [team-billing, '@alice']

$ owners who billing/api/invoices.py
path:    billing/api/invoices.py
owners:  team-billing, @alice
status:  active
slack:   #team-billing
source:  billing/owners.yaml
Previously, in code ownership

What you missed

The short version for anyone who was busy. No need to admit it. We will not tell the others.

The file
Any directory can hold an owners.yaml. It applies to that directory and everything below it. Two required fields: version and owners.
The rules
The nearest file wins, field by field. A rule only reaches paths below its own file. owners: null means unowned on purpose. Everything is in the spec, in numbered MUSTs.
The conformance suite
About 100 cases, written as data. Write a resolver in any language, run the cases, and you get the same answers as everyone else.
The reference implementation
owners-yaml on PyPI: a CLI, a Python library, a JSON entrypoint, and a linter. Your GitHub required reviews keep working, because CODEOWNERS stays where it is.

The comparison table where we win every row

One CODEOWNERS file
owners.yaml files
Who wins a conflict
The last line. Good luck.
The nearest file
Merge conflicts
A team sport
Your file, your problem
Lint
Vibes
Dead globs, broken files, coverage. Real teams with --live
Anything besides owners
A comment, if you are lucky
Status, Slack channels, bot opt-outs
Required approvals on GitHub
Yes, and it is good at it
Keep CODEOWNERS for that. We do not mind.
The last row is us being fair. It felt strange.

Should you catch up?

Worth it when
  • Several teams share one repo, and ownership changes directory by directory.
  • Your CODEOWNERS file collects merge conflicts, or a line near the bottom keeps taking over paths.
  • Review bots, alert routers, or agents need owners, a status, or a team channel as data.
Keep plain CODEOWNERS when
  • Your CODEOWNERS file is a few dozen lines, and nobody fights over it.
  • All you need is GitHub blocking merges on an owner's approval. CODEOWNERS does that, and owners.yaml does not.
  • You rely on GitLab or Bitbucket code owner approvals. The tool reads GitHub teams and handles.
  • You need a stable 1.0 Python API. The package is 0.x, and the file format is at version 1.
Trusted by companies we made up for this section
Blamr YAMLworks Mergely Flakebase Monolith & Sons PostHog (real, about 30 teams)

Everything you need. Nothing on a blockchain.

Six features in a three-column grid, as the law of landing pages requires.

Blazingly nearest
Between files, the nearest one wins, field by field. A child that only sets owners keeps its parent's status. inherit: false cuts the cord. Inside one file, the last matching rule wins.
Rules that stay in their lane
A rule only reaches paths below its own file. A pattern added at the bottom of one giant file can no longer adopt half the repo.
Unowned, on purpose
owners: null says nobody owns this, and we meant it. Everything else without an owner shows up in owners unowned, in front of everyone.
A status field for robots
generated, vendored, deprecated. Your review bot skips the lockfile without keeping its own secret ignore list.
Knows where your team lives
One registry maps a team to its Slack channels, with a separate channel for automation and an opt-out per bot.
One resolver, three doors
A Python library, a CLI, and a JSON entrypoint that needs only PyYAML. Nobody reimplements the resolution steps in a bash script again.
Resolution got thorough enough that grep gets it wrong. Please ask the resolver: owners who <path>
Adopt the format in 6 easy steps

You only need the first two

No “book a demo”. Run it, put a file next to the code, ask. The other four steps cover settings, bots, CI, and your own tools.

1
Run it. Installing is optional.
uvx fetches the package from PyPI, so a laptop or a CI runner needs only uv.
# run once, nothing installed
$ uvx owners-yaml --help
# careful: "uvx owners" is a different PyPI package.
# always spell it uvx owners-yaml.

# or keep it around
$ uv tool install owners-yaml
$ pipx install owners-yaml   # also fine

# two identical commands
$ owners --version
$ owners-yaml --version
2
Put a file next to the code.
The smallest file sets a version and the owners. Teams are bare slugs, people are @handles.
# billing/owners.yaml
version: 1
owners: [team-billing, '@alice']

# rules change paths below this file only.
# inside this file, the last matching rule wins.
rules:
  - match: 'generated/**'
    status: generated
  - match: 'vendor/'
    owners: null      # nobody, on purpose
# then ask who owns a path
$ owners who billing/api/invoices.py
owners:  team-billing, @alice
Show the other 4 stepsHide the other 4 steps
3
Tell the root file about your repo.
Settings live only in the root owners.yaml. None of them is required. A team that is not listed still works, and its channel is derived from its slug.
# owners.yaml (the root file)
# format version. always 1.
version: 1
# repo-wide default owner. empty = none.
owners: []
# where lint --live looks up teams and @handles
github_org: acme
# bot names that teams may mention below
producers: [review-bot]
# other file names that count as ownership files.
# defaults to [product.yaml]. [] turns that off.
alias_files: []
# optional. only needed for channels.
teams:
  team-billing:
    slack: '#billing'               # people
    notifications: '#billing-bots'  # bots
4
Ask, do not read.
Resolution has more steps than a CODEOWNERS lookup, so ask the resolver.
$ owners who billing/api/invoices.py
owners:  team-billing, @alice
source:  billing/owners.yaml

# many paths, as JSON, args or stdin
$ git diff --name-only main \
    | owners resolve --json

# the JSON shape a bot gets
{
  "billing/api/invoices.py": {
    "owners": ["team-billing", "@alice"],
    "slack": "#billing",
    "source": "billing/owners.yaml",
    "status": "active"
  }
}

# the channel where bots should post
$ owners resolve --purpose notifications \
    billing/api/invoices.py
billing/api/invoices.py  team-billing, @alice  active  #billing-bots

# what nobody owns, and nobody decided that
$ owners unowned
5
Lint it in CI.
Pin the version. A new release can change how a path resolves.
# .github/workflows/owners.yml
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10.2.0
      - run: uvx owners-yaml==0.2.0 lint
# also check slugs and handles against GitHub
$ owners lint --live
# plain lint does not know which teams exist.
# --live asks GitHub through the gh CLI, which must be
# signed in and allowed to read the org's teams.

# see where files could merge or split. never writes.
$ owners fmt

# run lint before you trust who: a file that does not
# parse is skipped, and the parent answers instead.
6
Call it from your own tools.
A Python library, and a JSON entrypoint for every other language.
from owners_yaml import OwnersResolver

resolution = OwnersResolver().resolve(
    "billing/api/invoices.py"
)
resolution.owners  # ['team-billing', '@alice']
# any language: paths in, one JSON object out
$ echo web/app.ts | \
    uvx --from owners-yaml==0.2.0 \
    python -m owners_yaml --repo-root .
Bonus level
Resolve without a checkout
A server that routes alerts has no worktree. Give the resolver anything with a read(path) method: a repository API, an unpacked archive, a dict in a test. read returns None for a missing file. Add read_all(paths) and map() fetches the whole batch before it reads anything.
Some tools read only CODEOWNERS. For test analytics, owners codeowners -o CODEOWNERS.generated writes the owner of every test file in that syntax. owners census counts test files per owning team.
from owners_yaml import OwnersResolver


class ApiSource:
    def read(self, path: str) -> str | None:
        # your repository API
        return fetch_file_or_none(path)

    def read_all(self, paths: list[str]) -> None:
        # optional: one batch, not N requests
        prefetch(paths)


resolver = OwnersResolver(source=ApiSource())
resolver.map(["billing/api/invoices.py", "web/app.ts"])
For the robots in your repo

We are contractually required to say “agentic” once.

CODEOWNERS answers one question for one consumer: who must approve this pull request on GitHub. The bots around your repo have other questions, and they ask them at three in the morning.

Loved by things that cannot love

“For years people asked me who owns a file. I only know who touched it last. It was always the person who ran the formatter.”
git blame, reluctant oracle
“I used to request review from eleven people and hope. Now I request it from the right two. They still ignore me, but accurately.”
A review bot
“Nobody has read me since the reorg. I matched everything below me and I regret nothing.”
A wildcard near the bottom of CODEOWNERS
“I was asked whether everything was correct. I said yes. Then I checked. I would like to retract the first answer and keep the second.”
The agent that wrote this package, now humbler

Questions a sensible person asks

Is this an actual standard?
It has a written spec at version 1, marked stable, a JSON Schema for editors, and a conformance suite. No committee voted on it. One company runs it today, across about 30 teams. That is how most standards start, we are told.
Can I write my own resolver?
Please do. The spec defines the resolution steps and a command interface, and the conformance cases check your answers. owners-yaml is the reference implementation, not the only one allowed.
How do I migrate my CODEOWNERS file?
By hand. There is no importer. Start with one owners.yaml per top-level directory, run owners unowned, and work down from there. It took us an afternoon per team, mostly arguing.
What happens to required reviews on GitHub?
Nothing. GitHub still reads .github/CODEOWNERS, and this tool never writes that file. Keep it for approvals. owners codeowners only exports test-file owners, for test analytics.
Where do team names come from?
A team is the bare slug of a GitHub team in github_org. A person is an @handle. lint --live checks that both exist. The teams: map is optional and only adds channels.
What does version: 1 mean?
The version of the file format. Every file carries it, and 1 is the only version there is. It lets a future format change fail loudly and not quietly.
What is producers for?
It lists the bots that teams may name in their settings. lint rejects a bot name that is not on the list, so a typo does not silently route alerts nowhere.
Can each bot get its own channel?
Yes, notifications also takes a map of bot name to channel, and false mutes one bot. Today only the Python API reads that form: team_channel(slug, teams, "notifications", producer="review-bot"). The CLI reads the plain string.
Full disclosure

Agent-engineered. Supervised by seniors who know what they are doing.

An AI typed most of this package. A person with opinions read it, argued with it, and sent it back. Several times. Both of them would like you to know that.

A spec, so the agent cannot improvise
The format is written down with RFC 2119 keywords. When the agent gets creative, the spec says MUST NOT and the argument is over.
About 100 conformance cases
We do not trust it either. Every resolution rule has a case that fails loudly, in any language, before a human has to notice.
Reviewed by bots, then by people
Several review bots read every diff. They are also AI. It is AI most of the way down, and then there is a tired human with merge rights.
Do not like that? Do not use it.
It is a small MIT-licensed package that reads YAML files. You can read all of it before your coffee gets cold. You will be fine.
how the code review actually went
agent> Done. Everything is correct.
human> So you think all of this is right,
       and you verified nothing?
agent> ...
agent> I will now verify things.
fix: three things that were not correct
human> Why is this hardcoded?
agent> It is a sensible default.
human> It is my company name.
fix: move PostHog out of the general tool
# repeat until the spec and the human agree

Simple, transparent pricing

Hobby
$0
It reads YAML files. MIT license. You already have the whole product.
Enterprise
$0
Same package, but we say “governance” while you install it. SSO not included, because there is nothing to log in to.