CODEOWNERS Validation
Validate every `CODEOWNERS` change on every pull request — syntax, owners, and duplicate patterns — without rotating a personal access token.
A
CODEOWNERS file maps repository paths to the users and teams who must review changes to them before they can merge. The format fails open — a typo'd team or stray inline comment causes GitHub to silently drop the broken owner, and the affected paths lose review coverage with no error reported on the pull request that introduced the regression. Atmos Pro catches these mistakes on the PR by folding the validator result into the existing Atmos Pro check that already gates merges.The validator only runs when a pull request actually modifies one of GitHub's three
CODEOWNERS lookup paths. Every other PR is left alone — no noisy passing check on every commit.Open the repository in Atmos Pro and switch on Validate
CODEOWNERS on pull requests in the Settings tab. The toggle is workspace-admin gated and is off by default for every repository.Validate CODEOWNERS on pull requests
When a pull request modifies a CODEOWNERS file, Atmos Pro posts a check run that validates syntax, verifies every referenced user and team exists, and flags duplicate patterns. The check is skipped on PRs that don't touch CODEOWNERS.
Once the toggle is on, every new pull request that touches
CODEOWNERS is validated as part of the existing Atmos Pro composite check. There is no second check run to add to branch protection — the same required-status-checks rule that already gates merges on affected-stack results now also gates them on CODEOWNERS quality. A CODEOWNERS failure flips the composite check to failure even when every affected-stack workflow passes.The validator runs the same three checks as our long-standing
cloudposse/github-action-validate-codeowners action — the same defaults mszostok/codeowners-validator exposes under those names.| Check | What it catches |
|---|---|
syntax | Lines that don't follow <pattern> <owner1> [<owner2> ...]. Inline # comments are rejected because GitHub silently strips trailing tokens after a #, dropping owners. |
owners | Every @user is resolved with GET /users/:login. Every @org/team is resolved with GET /orgs/:org/teams/:slug. Emails are validated syntactically but not looked up. |
duppatterns | The same file pattern listed on two different lines — the second one wins in GitHub's parser, which often isn't what you meant. |
The validator scans the three lookup paths GitHub itself reads, in priority order:
CODEOWNERS, .github/CODEOWNERS, and docs/CODEOWNERS. Whichever exists at the PR head SHA is the one that gets checked.Three kinds of owner references are recognized:
@username— verified to exist as a real GitHub account.@org/team-name— verified to exist as a team in the repository's owning organization. Teams in other organizations can't be checked from a single installation token and are flagged accordingly.email@example.com— accepted if it parses as an email. GitHub itself uses the email to match against a contributor's verified emails, so we don't try to resolve it server-side.
The
owners check needs read:org to enumerate teams. GitHub Actions' built-in GITHUB_TOKEN is repository-scoped and doesn't expose that permission, so the third-party action requires a long-lived PAT in every repo — a per-repo rotation tax that has caused recurring drift across our open-source repos.Atmos Pro already runs as a GitHub App installed at the org level with
Organization → Members: Read. The validator uses the App's installation token, so there's nothing to rotate, nothing to store in repository secrets, and the same control plane works across every repo in the workspace.The validator uses the existing Atmos Pro GitHub App installation token. No new permissions are required if your App is already installed for Atmos Pro's other features. The relevant scopes are:
Pull requests: Read— to list files changed in the PR.Contents: Read— to fetch theCODEOWNERSfile at the head SHA.Checks: Write— to post the result back to GitHub.Members: Read(organization-scope) — to resolve@org/teamreferences.
The
Members: Read permission ships with Atmos Pro installations by default; if you locked your installation down to a custom permission set, ensure it's still granted.When the validator finds issues, they appear in the rolled-up Atmos Pro PR comment grouped by check (
syntax, owners, duppatterns) with line numbers, alongside any affected-stack output. The composite Atmos Pro check on the PR also flips to failure with a title like CODEOWNERS validation failed (3 issues) so the failure is visible in the PR sidebar at a glance. Fixing the listed lines and pushing a new commit reruns the validator against the new head SHA and re-rolls the composite check.