Threat model¶
Extra CODEOWNERS helps decide whether a pull request may merge. Its most important failure is a false success: the check reports that an owner approved the change when no eligible owner did. That is a security incident, not flaky CI.
This model covers the self-hosted GitHub App. There is no multi-tenant hosted service today. Such a service would need a separate design for tenant isolation, billing, abuse, and privacy before it could launch.
What the service protects¶
The protected assets are:
- repository merge policy and the integrity of required checks
- GitHub App private keys, webhook secrets, setup-state secrets, and short-lived installation tokens
- organization App enrollment and repository delegation policy
- private repository metadata, including paths, ownership, reviews, and team membership
- durable queue and audit records that explain decisions.
Where trust changes¶
GitHub -- HMAC-signed POST --> shared HTTPS origin: /webhooks/github
operator network ----------> same origin: health, identity, metrics, setup
|
v
queue and audit database
|
v
evaluation workers
| |
short-lived token | | sanitized data
v v
GitHub checks and operator output
operator secret manager --------> webhook boundary and workers
organization administrators ----> organization enrollment policy ----+
repository maintainers ---------> base-commit delegation policy -----+--> workers
GitHub authenticates the installation and signs the webhook body. The request then crosses the public boundary into the operator's service. Only the exact webhook path needs public ingress. Health, runtime identity, metrics, documentation, and setup may share the origin, but the proxy must restrict those paths to operators. The application does not authenticate them.
A durable queue separates accepting an event from evaluating it. Workers cross back into GitHub with short-lived, installation-scoped tokens.
Policy crosses a different boundary. Organization administrators decide which App identities may be trusted. Repository maintainers may delegate to those Apps, but only within the organization's guardrails and using policy from the current target-branch commit. The branch is resolved through GitHub's reference API because the PR's reported base SHA can remain stale after a branch update.
The operator trusts the database and secret manager. Checks, logs, metrics, and runtime identity usually have a wider audience, so they are lower-trust outputs. Runtime identity is a service self-report, not provenance evidence. Credentials and complete private payloads must not cross into any of them.
Threats, controls, and residual risk¶
No one control carries the design. Each row names the control that reduces a threat and the risk left after that control. The residual-risk column is part of the security contract.
| Threat | Control | Residual risk |
|---|---|---|
| A pull-request author edits delegation policy to authorize that pull request | Load repository policy and CODEOWNERS from the current target-branch commit, then revalidate the branch before publishing. Assign policy paths to humans in CODEOWNERS and make those paths non-delegable by default. | A merged policy change governs subsequent evaluations of open PRs as well as new PRs, so human review of it remains critical. This also prevents the pull request that first enables policy-file delegation from using that new authority. |
| A pull-request author edits the DCO checker that evaluates the same pull request | Keep the active workflow read-only and secretless. The replacement evaluator is pure, does not execute pull-request content, and is intended to run from an independently controlled GitHub App. | The independent caller and required context do not exist yet. Until issue #40 is complete, the active workflow remains review evidence rather than an enforcement boundary. |
| A retarget or force-push changes the DCO commit range while evidence is collected | Select commit IDs through the GraphQL pull-request connection, require the exact repository, base, and head identity on every list and detail response, and require matching event, before, and after snapshots. | Publication-time revalidation is not implemented. Same-repository and private-fork commit-node reads still need live contract tests before rollout. |
| Organization enrollment policy is changed maliciously | Keep enrollment in the separately governed organization-policy repository (.github by default), with native human CODEOWNER enforcement. |
Compromise of that repository's merge authority can expand application trust across repositories. |
| The organization-policy repository or installation account is renamed, transferred, deleted, changes default branch, or the policy repository is removed from App selection | Subscribe to repository, organization, installation-target, and repository-selection events. Treat malformed removal evidence as loss of the policy source, durably fan out current-state reevaluation, store an enqueue-time installation authority epoch, and reject queued routes that disagree with GitHub's authoritative base-repository identity. | Access loss can prevent revocation. A visible success may remain until the delivered event and fan-out finish, or until reconciliation recovers a missed delivery. |
| A target repository is renamed or transferred | Subscribe to repository lifecycle events, advance the enqueue-time installation authority epoch, rediscover current repository names, reject delayed old-name jobs against the authoritative base-repository identity, and serialize Check Run writers by installation and head. | A transfer can remove App access before an earlier success is revoked. Use the safe access-removal sequence unless destination access is already assured. |
| An archived repository with an earlier success is unarchived | Subscribe to repository.unarchived, durably schedule installation-wide current-state reevaluation, and leave native code-owner enforcement in place until it finishes. |
The old success may remain through webhook processing and fan-out, or until reconciliation recovers a missed delivery. |
| An application expands its authority through workflow or local-action code | Make .github/workflows/** and .github/actions/** non-delegable by default. |
A privileged workflow can invoke code elsewhere. Organization guardrails must include those repository-specific paths. |
| An application changes its own approval policy or decision code | Make Stampbot's root /stampbot.toml non-delegable by default. Require organization guardrails for every other enrolled App's local configuration and transitive decision inputs. |
Extra CODEOWNERS cannot infer arbitrary App control files. An incomplete inventory can permit self-expansion. |
| A forged or modified webhook asks for success | Verify HMAC-SHA256 over the raw body before parsing, then fetch authorization evidence from GitHub. | A stolen webhook secret permits forged triggers, but not forged GitHub API evidence. |
| A crafted path, owner, or diagnostic forges trusted-looking Check Run content | Use a fixed evidence layout, render controls visibly, escape Markdown prose, and HTML-escape code-like values. | Check details still expose decision metadata to anyone who can view the repository. |
| GitHub redelivers an event | Deduplicate X-GitHub-Delivery transactionally. The retained delivery keeps the original head identity and the shared-generation token accepted for that head. If a pending fast-path retry discovers that the pull request has moved, it separately advances the live head's shared and evaluation generations and queues that head for invalidation. Prune delivery IDs after a configurable retention period. |
An expired ID may enqueue another evaluation, but authorization evidence is fetched again. Retention must cover the operator's redelivery window. |
| A webhook is missed | Subscribe to authority changes, reconcile accessible open pull requests periodically, and support operator-requested GitHub redelivery. When reconciliation inserts missing work for a canonical head, it advances the shared generation in the same transaction. A recheck that's due only because time passed doesn't advance it: the worker keeps the published result and writes the check only when the new evaluation differs. | A stale result can remain until the scan inserts work and a worker reaches GitHub. On a timer recheck, that includes the evaluation itself, because nothing blocks the check first. If that evaluation fails, loses its worker, or is deferred past one recheck interval, the retry advances the shared generation and blocks the check before evaluating again. Reconciliation leaves an existing active or delayed row unchanged. |
| A review is dismissed or changed after a successful check | Accept the review webhook durably, reset the managed check to an explicit failure before evaluation, verify that GitHub confirms the blocking state, require fresh exact-head evidence, and reconcile open pull requests. |
GitHub delivery and Check Run updates are asynchronous. A prior success can remain mergeable between the review change and the App's reset; reconciliation repairs missed delivery but cannot eliminate this window. Keep native code-owner enforcement where that window is unacceptable. |
| A head or base-branch commit arrives during evaluation | Require reviews for the exact head, fetch base and head again before publishing, and enqueue direct or base-ref fan-out work. | GitHub's check display remains eventually consistent during rapid changes. |
| Contributor-controlled branch names create unbounded work or repeat closed history | Keep one discovery job per installation and repository. Up to 100 target branches share each current or next listing pass; overflow broadens that batch to every base. Claim installation work and batches covering every base before ordinary targeted work. | New pushes during a scan can require another pass. The shared repository fence can delay queued PRs outside its target branches; even urgent discovery can exhaust GitHub quota. |
| Several pull requests share one head commit but need different decisions | Refuse success when another open PR already uses the head. Every accepted direct trigger advances a shared generation and durably queues revocation for that commit. With a managed check, invalidation fetches current state for every commit-to-pulls candidate, resets the check only while an associated PR remains open, and binds open peers to the current generation. Without a check, it skips reset and fan-out. An enrolled evaluation with an older generation requeues itself rather than discarding its work; success still requires fresh shared-head evidence. If all associated PRs are closed, completed results are preserved and unfinished work is cancelled. Publication requires the captured, current, and invalidated generations to match. | A PR opened or retargeted after success can inherit that commit-scoped result until GitHub delivers its webhook and the service accepts it. The commit-to-pulls response has no completeness marker, so an omitted candidate is also undetectable. These provider assumptions block production use until the live contract proves the control. |
| A mapped review, label, pull-request, or rerequest trigger races with evaluation | Record the trigger, its pull-request generation, its shared-head generation, and pending exact-head invalidation in one transaction. Bind the fast path to that generation. Lease durable invalidation ahead of evaluation, and recheck lease ownership immediately before the reset. Before completion, verify the captured generation is current and invalidated. Recheck the evaluation lease immediately before and after the completed write while holding the head publication guard. Treat an error or cancellation during the write or post-publication verification as uncertainty and attempt a shielded reset to a blocking result before releasing the guard. | GitHub may apply a write before its response is lost. A hard process stop or failed reset can leave that completed result visible until fast invalidation or durable retry reaches GitHub. |
| A policy label is renamed or deleted | Subscribe to label-definition events, fan out repository evaluation, and fetch current pull-request label names. | Success may remain visible while processing and fan-out finish, or until reconciliation recovers a missed delivery. |
| A rename moves content across ownership boundaries | Evaluate both the old and new path. | GitHub must provide the previous path. Incomplete rename evidence fails closed. |
| GitHub truncates a very large pull request | Paginate and reject evaluation at GitHub's 3,000-file API maximum because completeness can no longer be proved. | Such a pull request must be split before it can use Extra CODEOWNERS. |
| Adversarially large payloads or policies exhaust service resources | Bound webhook bodies, policy and CODEOWNERS size, review and membership evidence, GraphQL DCO pages, aggregate commit-message bytes, and path-pattern operations. Project sign-off and signature predicates instead of retaining raw messages or signature blobs. Reject unknown policy fields. | Work beyond a bound blocks authorization and may require splitting the pull request or policy. |
| An unenrolled bot copies a trusted App's name | Require the review bot's user ID, Bot type, and exact <slug>[bot] login. Fetch that bot user through the repository installation and require the returned immutable ID to match the organization enrollment. |
GitHub review APIs do not expose the originating App ID. The protected organization policy binds the App ID, slug, and bot user ID, so changing that trust relationship still needs human review. |
| Automation uses a normal GitHub user account | Govern CODEOWNERS users and team membership outside this service. Reserve application delegation for actors GitHub identifies as Apps. | Actor type User does not prove personhood. A machine user with owner authority is treated like any other user. |
| An owner self-satisfies the Extra CODEOWNERS check | Default allow_author_as_codeowner to false. When a repository enables it, accept only the current pull-request author GitHub identifies as User after the same direct-owner or active-team repository-access checks used for a human reviewer. Keep ordinary review-count rules separate. |
The option intentionally permits an eligible author to satisfy matching owner sets, including non-delegable paths. It is appropriate only when that small-team trade-off is explicitly accepted. |
| A selected App approves a future change to its own repository policy | Default allow_delegation_for_policy_file to false. When a repository opts in, require the existing App identity, current-head review, matching owner set, and explicit policy-file delegation. Organization guardrails can still veto the path. |
The selected App can approve a later edit that expands its own future scope. Bootstrap the option with human review. If the App is compromised, add an organization guardrail through human-controlled policy before relying on a repository-policy change. |
| Human or team ownership eligibility changes after approval | Revalidate direct-user repository permission, team visibility, repository access, and active membership. Subscribe to repository and organization authority events and reconcile open pull requests. | Success may remain stale while event delivery and fan-out run, or until reconciliation recovers a missed event. |
| Contributors mistake a successful required check for an ordinary GitHub review | Name the check clearly, configure its expected App source, retain the intended numeric review rule, and expose the evidence in the Check Run output and operating documentation. | GitHub presents reviews and required checks in different parts of the pull-request UI. A repository can still misconfigure or misunderstand its rules, especially during rollout. |
| App access is suspended or an ordinary target repository is removed from its installation | Keep native human enforcement until access changes finish, and restore it before intentional removal. Acknowledge a well-formed ordinary-target removal without pretending revocation succeeded. | Once access is gone, Extra CODEOWNERS cannot revoke an existing check in that repository. |
| A trusted application is compromised | Limit delegation by path and effective owner, then preserve non-delegable paths. Use labels for workflow routing, not as a separate trust boundary. | Pull-request write permission lets the application change labels as well as submit its review. Within the path-and-owner scope, the application is intentionally trusted to approve. |
| The operator loses GitHub API access or reaches a rate limit | Fail closed, retry indefinitely with a configured maximum ordinary backoff, honor separately bounded provider Retry-After or reset timing, and expose queue state and API failures. |
Availability failures block merges while retries continue at bounded intervals. The service has no remaining-quota metric. |
| Another actor publishes a check with the same name | Require the Extra CODEOWNERS App as the expected source. Register the App with Commit statuses (statuses) write so GitHub can offer it as an organization-ruleset source, then omit that permission from runtime tokens. |
A rule configured by name alone is vulnerable to source confusion. |
| A proxy, browser, or observer captures App Manifest setup material | Require HTTPS and signed, short-lived state; suppress access logs; return no-store pages with a restrictive content security policy; disable setup after use. | The one-time callback and displayed conversion response contain credentials. A compromised operator endpoint or browser can disclose them. |
| The service or database is compromised | Use least-privilege App permissions, short-lived installation tokens, a secret manager, encrypted transport, and restricted database access. | Service compromise can falsify checks within installed repositories. Rotate the App key and investigate every affected check. |
Invariants¶
Implementation details may change. These properties may not. Each has a stable ID; a test that verifies one names that ID in a comment.
- XCO-001. Incomplete or contradictory evidence never yields success.
- XCO-002. A review for an older head never satisfies the current head.
- XCO-003. A repository cannot enroll its own trusted application.
- XCO-004. A label is never approval evidence by itself.
- XCO-005. Every distinct effective CODEOWNERS owner set is satisfied independently.
- XCO-006. Both names of a renamed file are evaluated.
- XCO-007. Check publication is bound to the exact evaluated head and the expected App source.
- XCO-008. A worker never treats an uncertain completed write or post-publication generation check as current. It attempts a shielded reset to a blocking result before releasing the writer guard and preserves the original exception or cancellation so durable work remains retryable.
- XCO-009. Relevant pending or retrying authority fan-out prevents publication of a completed result.
- XCO-010. A shared-head generation cannot publish until durable invalidation for that exact generation has finished.
- XCO-011. Credentials and raw private payloads never appear in logs, metrics, checks, or audit details.
- XCO-012. An independent DCO result identifies the repository, pull request, base SHA, and head SHA whose snapshot-bound commit connection produced it.
- XCO-016. A recheck driven only by time leaves the published result in place only for its first attempt. A failure, a lost worker, or a deferral that would retry more than one recheck interval after the recheck was queued blocks the check before the retry evaluates.
XCO-007 has an important limit. GitHub does not offer a pull-request-scoped required Check Run, so two pull requests can inherit the check attached to one commit. Shared-head detection and durable exact-head invalidation close the worker race after acceptance. They cannot eliminate the period before GitHub delivers and Extra CODEOWNERS accepts the relevant event.
The opt-in live GitHub contract fixture measures required-check invalidation, shared-head inheritance, retargeting, expected-source rulesets, App reviews, and sanitized webhook payloads against a disposable GitHub.com repository. A run is evidence for the tested API and account at that recorded time. It cannot prove instant or reliable webhook delivery, and it does not remove the production blocker while success can be inherited before invalidation. Its delivery-log probe follows GitHub's pagination metadata within fixed bounds. When another page remains, an unseen delivery is incomplete evidence, not evidence that the delivery was absent. The same rule applies to cleanup: after an ambiguous repository create, repeated 404 responses trigger manual verification rather than a successful cleanup claim.
The dated live results distinguish tested behavior from the merge and access-loss paths that remain open. Successful approval tests do not remove the shared-head limitation above.
Why some paths cannot be delegated¶
Some files decide who may approve. Others decide what trusted automation will do. If an App can approve changes to those files, it may be able to enlarge its own authority.
Extra CODEOWNERS therefore has this built-in non-delegable set:
- every standard CODEOWNERS location
- Stampbot's root
/stampbot.toml .github/workflows/**- repository-local actions under
.github/actions/**.
The effective Extra CODEOWNERS policy path, which defaults to
.github/extra-codeowners.toml, is also non-delegable by default. A repository
may set allow_delegation_for_policy_file = true to let an explicit matching
delegation cover that one path. The option never affects the other built-ins,
and an organization guardrail for the path still wins.
Organization policy may add paths, and repository policy cannot remove those guardrails. When a changed, owned path matches the effective set, an App approval cannot replace approval from an eligible human.
The service cannot discover every input used by a privileged workflow or an
approving App. Stampbot is one known case, not a complete inventory. Use
organization guardrails.non_delegable_paths for each enrolled App's local
configuration, rules, prompts, generated inputs, and decision code. Include
repository-specific release scripts, deployment helpers, action code outside
.github/actions/, and anything else that can change trusted behavior. Review
the transitive set whenever an App, workflow, or approval policy changes.
“Non-delegable” is about approval, not authorship or contents. Apps may appear in workflows and configuration. They just cannot stand in for the appropriate human when a pull request changes an owned protected path.
Nor does the list assign an owner. Repositories must still cover these paths in standard CODEOWNERS. An unowned path creates no code-owner requirement in GitHub's native model or in Extra CODEOWNERS.
What the insecure-changes escape hatch changes¶
Setting EXTRA_CODEOWNERS_ALLOW_INSECURE_CHANGES=true removes the built-in
non-delegable set for every installation served by that process. The setting's
name is deliberately blunt. While enabled, it produces a high-severity startup
warning and an always-on metric.
It does not:
- remove organization-defined non-delegable paths
- create or broaden repository delegation
- bypass path, owner, label, identity, or exact-head checks
- change GitHub's numeric review-count requirement
- bypass another required check.
Use the escape hatch only when a separate, independently enforced control protects ownership files, Extra CODEOWNERS and Stampbot policy, workflows, and local actions. Keep that deployment away from repositories that rely on the built-in guardrails. Record the exception owner, reason, compensating control, and expiry.
Secrets¶
Secrets give the service its GitHub identity:
- Store the App private key and webhook secret in a managed secret store, not in a repository, image, policy file, command line, or log field.
- Prefer file-mounted secrets over multiline environment values when the platform supports them.
- Let the runtime identity read only the specific secret versions it needs.
- Rotate the webhook secret and App private key after suspected disclosure, operator departure, or service compromise.
- Treat installation access tokens as short-lived cache material. Never persist them in the durable queue or audit store.
After private-key compromise, remove its authority first: suspend the App or revoke the key. Restore native human code-owner enforcement on affected repositories, rotate credentials, and review every check published during the exposure window.
Boundaries not yet implemented¶
The implementation does not currently cover:
- GitHub Enterprise Server, until named server versions have been tested
- high-assurance merge queues, until
merge_groupreevaluation is implemented and tested - a transfer or installation change that removes repository access before control returns to native enforcement
- tenant isolation or service-level commitments for a hosted multi-tenant service
- arbitrary third-party callers; the webhook endpoint authenticates GitHub, not a general API client.
The remaining work list links the issues that track these boundaries.