mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-09 01:35:18 +02:00

Andrew Altshuler c7365bf8ef

ci(codeowners): un-trap required checks, auto-render, generate owner tables (#142 )

The CODEOWNERS required checks blocked every PR — the real root cause was a
name mismatch, compounded by a path filter:

- branch-protection.json required the contexts `CODEOWNERS / drift` and
  `CODEOWNERS / noedit` (the GitHub UI "workflow / job-id" display form), but
  the jobs report check-run names from their `name:` fields — "CODEOWNERS
  matches source" / "CODEOWNERS not hand-edited". The required contexts
  therefore never matched any reported check and sat permanently pending.
- The workflow was also path-filtered to CODEOWNERS files, so it didn't even
  run for most PRs.

Net effect: with both required checks unsatisfiable, every PR could only land
via admin override (e.g. #140).

Fixes:
- A: drop the `paths:` filter so the workflow runs on every PR and both
  required contexts always report.
- name fix: point branch-protection.json at the actual job names verbatim, and
  add a doc note that the contexts must equal the job `name:` values.
- B: the `drift` job now re-renders and, on same-repo PRs, auto-commits the
  regenerated artifacts back to the branch (mirrors the openapi.json job in
  ci.yml); forks / manual runs strict-check instead. Contributors no longer
  run the script by hand.
- D: render-codeowners.py also generates a "who owns what" path->owners +
  roles table spliced into docs/dev/codeowners.md between markers, so the
  human-readable view never drifts. Idempotent; CODEOWNERS output unchanged.
- docs: correct the stale `enforce_admins: true` line (JSON and live are
  false).

NOTE: the branch-protection.json change only takes effect after an admin runs
`./scripts/apply-branch-protection.sh` (deliberate manual step, per
docs/dev/branch-protection.md). Until then `main` still requires the old
mismatched contexts, so this PR itself needs an admin-override merge — the last
one that should be necessary.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-06 18:09:47 +03:00

3.3 KiB

Raw Blame History

Code ownership

.github/CODEOWNERS is generated — not hand-edited. The source of truth is .github/codeowners-roles.yml, expanded by .github/scripts/render-codeowners.py. CI rejects drift between the two and rejects direct edits to CODEOWNERS that don't accompany a yml change.

This setup gives every role change a reviewable PR and a permanent in-repository audit trail (git log .github/codeowners-roles.yml).

Who owns what

The tables below are generated from .github/codeowners-roles.yml by .github/scripts/render-codeowners.py (the same render that produces .github/CODEOWNERS). They are the always-current "who owns what at this commit" view — don't edit them by hand; edit the yml and re-render.

Path → owners (GitHub applies last match wins; the * catch-all is listed first and is overridden by the specific patterns below it):

Path	Owners	Role(s)
`*`	@ragnorc	engineering
`crates/**`	@ragnorc	engineering
`docs/**`	@ragnorc	docs
`README.md`	@ragnorc	docs
`AGENTS.md`	@ragnorc	docs
`CLAUDE.md`	@ragnorc	docs
`SECURITY.md`	@ragnorc	docs

Roles:

Role	Members	Description
`engineering`	@ragnorc	All production code under crates/**. Engine, CLI, server, compiler.
`docs`	@ragnorc	Documentation under docs/**, plus repo-level docs (README.md, AGENTS.md, CLAUDE.md symlink, SECURITY.md).

GitHub treats multiple owners on a CODEOWNERS line as "any one of them satisfies the review requirement". To require N distinct approvers on a specific path, layer a CI check on top (not currently configured).

How to change role membership or path mappings

Edit .github/codeowners-roles.yml.
Open a PR. CI re-renders for you: the CODEOWNERS workflow regenerates .github/CODEOWNERS and the ownership tables above and auto-commits them back to your PR branch on same-repository PRs — you don't have to run the script locally (though you can: python3 .github/scripts/render-codeowners.py, requires PyYAML).

On a fork (where CI can't push back), the workflow instead fails with the diff so you can run the script and commit it yourself.

CI fails the PR if:

a fork PR left a generated artifact out of sync, or
CODEOWNERS was edited without a corresponding yml change (the CODEOWNERS not hand-edited check).

How to add a new role

Add a new entry to roles: in the yml with a description and members list.
Reference the role from paths: (or default:).
Regenerate + commit as above.

Why a generator, not direct CODEOWNERS edits?

Audit trail: git log .github/codeowners-roles.yml is the canonical record of every role change. The rendered CODEOWNERS is a derived artifact.
Roles are first-class: paths reference roles, not raw handles. Renaming a person or rotating a role updates one place, not every path.
Future extension: scheduled rotation (weekly on-call, quarterly leads) plugs into the same yml without changing the path mappings. Not enabled today.
Consistency with the product: omnigraph itself enforces auditable Cedar policy. The repository's code-owner policy follows the same "policy as reviewed code" pattern.

3.3 KiB Raw Blame History