Skip to content

Configuration reference

This page defines the typed settings and policy models for version 0.1. The checked-in models, validation tests, and current schema are authoritative. Compatibility may change before 1.0.

Configuration has three scopes:

  • Runtime settings configure an operator's deployment.
  • Organization policy enrolls applications and defines guardrails.
  • Repository policy opts a repository in and delegates specific paths.

The runtime EXTRA_CODEOWNERS_GITHUB_APP_ID identifies the checker that publishes the required Check Run. Entries under organization apps identify applications whose existing pull-request approvals may substitute for humans, such as Stampbot. The checker App ID belongs in an enrollment only if that App also submits reviews independently. Extra CODEOWNERS does not submit reviews.

Policy locations

The default policy path is .github/extra-codeowners.toml. EXTRA_CODEOWNERS_POLICY_PATH changes it for the entire deployment. Both policy scopes use the same validated literal path. A repository cannot override it.

Scope Repository and revision Purpose
Organization <organization>/.github, default branch Enroll immutable application identities and add organization guardrails.
Repository Pull request's base repository, current target-branch commit Enable evaluation and delegate paths to an enrolled application.

Organization policy is not copied into target repositories and does not opt them in. Every target repository needs an enabled repository policy. Repository policy may narrow organization authority. It cannot enroll an application or weaken an organization guardrail.

Version 0.1 uses one configured policy path for both scopes. The organization-policy repository uses that path for organization policy, so it cannot also use the path as its own repository policy. The default organization-policy repository is the organization's .github repository.

Extra CODEOWNERS does not reconcile or evaluate pull requests for the organization-policy repository. It does not publish checks there. Pull-request webhooks for that repository are authenticated and acknowledged without retention.

The following organization-policy repository events are retained and fan out reevaluation to installed target repositories:

  • a relevant policy push to the default branch
  • a default-branch change
  • rename, transfer, or deletion
  • removal from the App's repository selection
  • a malformed repository-removal event.

The organization-policy repository must retain GitHub's native human code-owner enforcement. Extra CODEOWNERS must not be a required check there in version 0.1. Separate organization and repository policy paths are not supported.

Organization policy

The following example enrolls one application and adds a non-delegable path:

schema_version = 1

[apps.example-automation]
slug = "example-automation"
app_id = 123456
bot_user_id = 234567

[guardrails]
non_delegable_paths = [
  "terraform/production/**",
]

Organization fields

Field Type Required Meaning
schema_version integer yes Policy schema. Version 1 is accepted. Unknown versions fail closed.
apps table no Map of at most 50 local aliases to trusted application identities. Aliases contain letters, digits, internal hyphens or underscores, are normalized to lowercase, and are referenced by repository policy. Defaults to an empty table.
apps.<alias>.slug string yes GitHub App slug containing letters, digits, and internal hyphens, normalized to lowercase. Slugs must be unique across entries and are used for independent identity verification, not by themselves as authentication.
apps.<alias>.app_id positive integer yes Immutable GitHub App ID recorded by the organization administrator. IDs must be unique across entries. Boolean and string values are rejected.
apps.<alias>.bot_user_id positive integer yes Immutable numeric ID of the App's bot account. IDs must be unique across entries. Boolean and string values are rejected. Pull-request reviews identify this actor.
guardrails.non_delegable_paths array of strings no At most 100 additional CODEOWNERS-compatible patterns that always require an appropriate human approval. Defaults to an empty array. These are additive and cannot be removed by repository policy or the runtime escape hatch.

An application alias is local policy vocabulary; changing it requires updating repositories that reference it. Numeric IDs are the trust anchors. A slug mismatch, missing identity, or conflicting alias fails closed.

Repository policy

schema_version = 1
enabled = true

[[delegations]]
app = "example-automation"
paths = [
  "docs/**",
  "**/*.lock",
  "renovate.json",
]
for_owners = ["@example-org/platform"]
required_labels = ["automation-approved"]
forbidden_labels = ["needs-security-review"]

Repository fields

Field Type Required Meaning
schema_version integer yes Policy schema. Version 1 is accepted. Unknown versions fail closed.
enabled boolean yes Explicitly opts the repository in or out. A committed policy that omits enabled is invalid. An absent file in a repository with no managed check produces no check and no noise. An explicitly disabled file produces failure; removing policy after a check exists also updates that managed check to failure when evaluated.
allow_author_as_codeowner boolean no; false When true, a pull-request author GitHub identifies as a User may satisfy a matching owner set without a separate Extra CODEOWNERS review. The service requires the same current direct-user or team membership and repository-access evidence used for a human reviewer. It does not create a GitHub review or change an ordinary review count. An eligible author may satisfy a non-delegable owner set because the option intentionally treats that author as human evidence.
allow_delegation_for_policy_file boolean no; false When true, an enrolled App may satisfy the configured repository-policy file through an explicit matching delegations entry. The App's current-head review, identity, labels, and effective CODEOWNERS owner set still have to match. This affects no other built-in path. The base policy controls this field, and an organization guardrail for the path still wins. Enabling it lets the selected App approve later policy edits that may expand its future scope, so bootstrap it with human review.
delegations array of tables no At most 100 application delegations. With no entries, only appropriate human approvals can satisfy owned paths.
delegations[].app string yes Alias from the organization's apps table. Repository policy cannot introduce an application.
delegations[].paths array of strings yes Between 1 and 100 eligible changed-file patterns. A repository policy may contain at most 1,000 patterns across all delegations. All changed paths remain subject to standard CODEOWNERS ownership.
delegations[].for_owners array of strings yes Between 1 and 100 @user or @organization/team CODEOWNERS identities, normalized case-insensitively. Use "*" alone and explicitly to cover any owner set; omission, duplicates, or combining "*" with names is invalid.
delegations[].required_labels array of strings no At most 50 labels that must all be present before this delegation is eligible. Matching is case-insensitive. Labels gate evaluator behavior but are not independent authority: an App with pull-request write permission can change them.
delegations[].forbidden_labels array of strings no At most 50 labels that must all be absent. Matching is case-insensitive and defaults to an empty array. A label cannot be both required and forbidden. Treat this as workflow routing, not containment for a compromised App.

Multiple delegation entries are additive alternatives. For entries that overlap on an application, path, and owner set, any one entry with satisfied label conditions makes the application eligible. Restrictions from separate entries are not combined.

Every condition that must apply together belongs in one entry. A broader overlapping entry is not constrained by a narrower entry. Each entry must independently identify an enrolled application, eligible path, applicable owner, and label conditions. No entry can override an effective non-delegable path. The repository-policy file is an exception only when that repository explicitly enables allow_delegation_for_policy_file; an organization guardrail still overrides that choice.

Path pattern rules

Delegation and guardrail patterns follow standard CODEOWNERS-compatible matching:

  • Paths are relative to the repository root and use / separators.
  • Matching is case-sensitive.
  • A leading / anchors a pattern at the repository root.
  • A non-terminal / also makes a pattern root-relative: docs/* addresses the root docs directory. A trailing directory pattern such as apps/ can match an apps directory anywhere; write /apps/ to restrict it to the root.
  • A directory pattern ending in /, such as /docs/, matches files in that directory and all descendants.
  • A single * does not cross /; docs/* matches direct children but not docs/guides/start.md.
  • A double ** can cross directory boundaries; docs/** matches both direct children and nested descendants.
  • A ? matches exactly one non-/ character.
  • Negation with ! and character ranges with [] are not supported by CODEOWNERS and are invalid here.

An ownerless CODEOWNERS rule is valid and clears ownership for its matched path when it is the last matching rule. Extra CODEOWNERS therefore creates no code-owner requirement for that path, although ordinary review counts and other checks still apply.

GitHub supports some CODEOWNERS email identities. Extra CODEOWNERS version 0.1 does not. The evaluator cannot safely resolve an email entry to a review actor, so a relevant email owner fails closed. Supported identities are @user and @organization/team.

Policy files must be UTF-8 TOML and cannot exceed 1,000,000 bytes. Unknown fields are rejected. Policy should remain small enough for reviewers to inspect the complete authorization boundary. Standard CODEOWNERS has a separate 3 MiB maximum. A larger file fails evaluation because GitHub does not use it.

For a rename, Extra CODEOWNERS evaluates both the old and new path. A delegation must cover both names; otherwise the uncovered name requires an appropriate human approval.

See GitHub's CODEOWNERS syntax documentation for the baseline syntax.

Built-in non-delegable paths

The following paths reject application substitution by default:

/CODEOWNERS
/.github/CODEOWNERS
/docs/CODEOWNERS
/<configured repository policy path>
/stampbot.toml
/.github/workflows/**
/.github/actions/**

The restriction controls who may satisfy review policy for a change. It does not restrict file contents. Policy may list applications. Workflows and local actions may invoke applications.

The configured repository-policy path is non-delegable by default. Its default value is .github/extra-codeowners.toml; another validated EXTRA_CODEOWNERS_POLICY_PATH replaces it. A repository may set allow_delegation_for_policy_file = true to let a matching enrolled App cover only that path. The setting is read from the current target-branch commit, so the pull request that enables it cannot use it. An organization can veto the opt-in by adding the same path to guardrails.non_delegable_paths.

Non-delegable patterns do not assign ownership. Standard CODEOWNERS must give these paths an effective human user or team owner. Otherwise, Extra CODEOWNERS reports the path as unowned and creates no code-owner requirement. The CODEOWNERS file itself must be protected. GitHub's CODEOWNERS error view reports ownership errors that would weaken this boundary.

Organization guardrails.non_delegable_paths entries are added to this list and cannot be removed by repository policy. A repository may opt in only to the configured-policy-path exception described above; it cannot remove any other built-in path.

The built-in root /stampbot.toml entry protects Stampbot's repository policy because Stampbot is the first supported integration. Built-ins cannot discover every control file used by other enrolled applications. Organization policy must add these paths to guardrails.non_delegable_paths for each application:

  • policy and configuration
  • rules and prompts
  • generated-policy inputs
  • transitive decision code.

Without these guardrails, an application could approve a change that expands its future authority.

Organization guardrails must also cover repository-specific release, deployment, and helper paths that can alter privileged workflow behavior. A workflow can invoke code outside .github/actions/**. Extra CODEOWNERS cannot infer that transitive execution graph.

Runtime settings

Runtime settings use Pydantic Settings. Environment variables use the EXTRA_CODEOWNERS_ prefix. A local .env file is loaded when present. The serve command can override the host and port.

Unknown keys loaded from .env are rejected. Values outside documented bounds are also rejected. Unrelated process environment variables are ignored, except for the libpq connection variables listed below.

Service settings

Environment variable Type Default Constraints and effect
EXTRA_CODEOWNERS_ENVIRONMENT string development One of development, test, or production. Production refuses to start without the GitHub App ID, private key, and webhook secret.
EXTRA_CODEOWNERS_LOG_LEVEL string INFO One of DEBUG, INFO, WARNING, ERROR, or CRITICAL. Avoid debug logging for private production repositories unless its data handling has been reviewed.
EXTRA_CODEOWNERS_HOST string 127.0.0.1 Bind address. Use 0.0.0.0 only inside an appropriately isolated container or host.
EXTRA_CODEOWNERS_PORT integer 8000 Inclusive range 1 through 65535.
EXTRA_CODEOWNERS_PUBLIC_URL absolute HTTP(S) URL or null null Public origin used to construct the App Manifest webhook and one-use callback URLs. Setup mode requires an https:// origin with no credentials, no path other than /, and no query or fragment; otherwise this setting is optional.
EXTRA_CODEOWNERS_DATABASE_URL SQLAlchemy URL sqlite:///./extra-codeowners.db Durable queue and audit store. Production requires PostgreSQL through the exact postgresql+psycopg driver. The URL must contain one explicit host or Unix-socket path, database, username, and nonempty password. Treat the complete value as a secret. SQLite remains available for development and tests.

The production URL is the only database connection source. Percent-encode reserved characters in its username and password. Hostless and comma-separated multi-host URLs are rejected, as is an authority host combined with a query-string host. An explicit authority port must be between 1 and 65535; omission uses PostgreSQL's default port 5432.

Only three query parameters are supported:

Parameter Constraint
host Supplies the one host or Unix-socket path only when the URL authority omits its host.
hostaddr Supplies one nonempty address. It requires an explicit host and sslmode=require.
sslmode require or disable. A remote route requires require. It encrypts the connection but does not verify the database certificate or hostname. The application prevents libpq from loading its default root certificate, so that behavior does not vary with the process account. Certificate-verification modes are unsupported. An operator-controlled localhost, 127.0.0.1, ::1, or Unix-socket route may omit TLS or use disable when hostaddr is absent.

Unknown query parameters are rejected. In particular, service URLs, PGSERVICE, and PGSERVICEFILE are unsupported. The application also supplies the password directly, so it does not use .pgpass; PGPASSFILE is rejected. The runtime and migrator set gssencmode=disable so GSSAPI encryption cannot bypass the required SSL transport. They pin search_path=public instead of accepting caller-supplied libpq options.

Production startup and database commands reject these ambient variables when they are present, even with an empty value:

Category Rejected variables
Route and credentials PGDATABASE, PGHOST, PGHOSTADDR, PGPASSWORD, PGPASSFILE, PGPORT, PGSERVICE, PGSERVICEFILE, PGUSER
Connection and session PGAPPNAME, PGCLIENTENCODING, PGCONNECT_TIMEOUT, PGDATESTYLE, PGLOADBALANCEHOSTS, PGMAXPROTOCOLVERSION, PGMINPROTOCOLVERSION, PGOPTIONS, PGTARGETSESSIONATTRS, PGTZ
Transport security PGCHANNELBINDING, PGGSSDELEGATION, PGGSSENCMODE, PGGSSLIB, PGKRBSRVNAME, PGREQUIREAUTH, PGREQUIREPEER, PGREQUIRESSL, PGSSLCERT, PGSSLCERTMODE, PGSSLCOMPRESSION, PGSSLCRL, PGSSLCRLDIR, PGSSLKEY, PGSSLMAXPROTOCOLVERSION, PGSSLMINPROTOCOLVERSION, PGSSLMODE, PGSSLNEGOTIATION, PGSSLROOTCERT, PGSSLSNI, PGSYSCONFDIR

PostgreSQL access has fixed fail-fast budgets:

Operation Timeout
Establish a connection 3 seconds
Obtain a pooled connection 2 seconds
Execute an ordinary statement 3 seconds

Advisory-lock acquisition replaces the statement timeout with that operation's bounded guard wait. These values are not runtime settings. A database path that cannot reliably meet them causes webhook acceptance or worker operations to fail closed and retry where applicable.

GitHub settings

Environment variable Type Default Constraints and effect
EXTRA_CODEOWNERS_GITHUB_APP_ID positive integer or null null Numeric ID of this Extra CODEOWNERS App. Required for GitHub processing.
EXTRA_CODEOWNERS_GITHUB_PRIVATE_KEY secret string or null null Inline PEM private key. Literal \n sequences are converted to newlines. Mutually exclusive with the file setting.
EXTRA_CODEOWNERS_GITHUB_PRIVATE_KEY_FILE path or null null File containing the PEM private key. Preferred for deployed workloads. Mutually exclusive with the inline setting.
EXTRA_CODEOWNERS_GITHUB_WEBHOOK_SECRET secret string or null null Inline webhook HMAC secret. Production requires at least 32 UTF-8 bytes. Mutually exclusive with the file setting.
EXTRA_CODEOWNERS_GITHUB_WEBHOOK_SECRET_FILE path or null null File containing the webhook HMAC secret. Production requires at least 32 bytes after one terminal line ending is removed. Preferred for deployed workloads. Mutually exclusive with the inline setting.
EXTRA_CODEOWNERS_GITHUB_API_URL absolute HTTP(S) URL https://api.github.com REST API origin. Production requires HTTPS. Alternate GitHub deployments are not supported until version-specific integration tests exist.
EXTRA_CODEOWNERS_GITHUB_API_VERSION string 2026-03-10 Value of X-GitHub-Api-Version, currently a supported GitHub REST API version. Change only after compatibility testing.
EXTRA_CODEOWNERS_GITHUB_IDENTITY_PROBE_INTERVAL_SECONDS number 30 Seconds between authenticated App identity probes; inclusive range 5 through 300. Each probe calls GET /app with the configured private key and requires the returned App ID to equal EXTRA_CODEOWNERS_GITHUB_APP_ID.
EXTRA_CODEOWNERS_GITHUB_IDENTITY_FRESHNESS_SECONDS number 90 Maximum age in seconds of the last successful identity probe; inclusive range 10 through 900. It must be at least twice the probe interval. Readiness fails after this window without a successful refresh.
EXTRA_CODEOWNERS_GITHUB_MAX_IN_FLIGHT_REQUESTS integer 8 Maximum GitHub requests in flight per process; inclusive range 1 through 64. A durable rate-limit circuit pauses claims for the affected installation, or every installation for an App-wide limit, across all pods.
EXTRA_CODEOWNERS_GITHUB_RECOVERY_RESERVE_PERCENT integer 20 Percentage of each installation's observed REST core limit reserved for direct events, discovery blocking those events, and identified revocations; inclusive range 1 through 90. Recovery and background authority discovery pause at this threshold until the provider's reset time. Replicas share the budget in the database. This does not increase GitHub's quota or reserve GraphQL points.

Secret-file readers support projected Kubernetes Secret symlinks while limiting resolution to 16 symlinks and 256 path operations. The resolved target must be a regular UTF-8 file no larger than 64 KiB. The service opens every path component with no-follow descriptor flags and rejects a file that changes while it is read.

Readers remove at most one terminal LF or CRLF, as commonly added by secret tooling, and preserve all other bytes. Inline private keys may use literal \n sequences for PEM line breaks; webhook secrets are not newline-expanded. Empty credential values do not make the service ready.

GitHub connect, pool, read, and write waits each use a fixed 20-second inactivity timeout. The client also applies a 20-second wall-clock deadline to each non-streaming request, including the reconciliation requests used during graceful shutdown. These limits are not runtime settings.

Tracing settings

Tracing is disabled unless an operator enables it. When enabled, Extra CODEOWNERS exports OpenTelemetry spans over OTLP/HTTP. The service starts a new trace for its own work; it does not accept a traceparent value from an unauthenticated GitHub webhook.

Environment variable Type Default Constraints and effect
EXTRA_CODEOWNERS_TRACING_ENABLED boolean false Enables OTLP trace export. It requires EXTRA_CODEOWNERS_TRACING_OTLP_ENDPOINT.
EXTRA_CODEOWNERS_TRACING_OTLP_ENDPOINT absolute HTTP(S) URL or null null OTLP/HTTP traces endpoint, such as http://opentelemetry-collector.observability.svc:4318/v1/traces. Credentials, query strings, and fragments are rejected. Treat the destination as an operator-controlled telemetry boundary.
EXTRA_CODEOWNERS_TRACING_SAMPLE_RATIO number 0.1 Fraction from 0 through 1 of new traces to record. Start with 0.1 in a busy production installation; use 1 temporarily while investigating a performance incident.
EXTRA_CODEOWNERS_TRACING_INCLUDE_PRIVATE_METADATA boolean false Adds repository, pull-request, delivery, queue, and API-path details to traces and records exception events. Leave disabled unless the trace backend has suitable access control and retention.

Every trace has fixed service, version, environment, operation, queue-kind, and work-class attributes. With private metadata disabled, it omits repository names, pull numbers, commit SHAs, delivery IDs, API paths, payloads, headers, tokens, and exception text. Sampled spans bind trace_id and span_id to the structured logs emitted inside that span. Unsampled work does not add those fields, so logs do not imply that a trace exists.

For sampled, verified direct webhooks, the service retains an opaque local span identity with the delivery and links the later worker attempt to it. This does not import a traceparent header from GitHub and does not add GitHub metadata to the normal trace attributes. Delivery retention limits how long the worker can create that link.

The service attempts an identity probe during startup and continues in the background. A failed refresh does not erase a still-fresh success, which avoids dropping readiness for one transient request. Once the freshness window expires, /health/ready reports github_credentials: false until an authenticated GET /app succeeds with the exact configured App ID. Liveness does not depend on this probe.

Queue and reconciliation settings

Environment variable Type Default Constraints and effect
EXTRA_CODEOWNERS_REQUIRE_POSTGRESQL boolean false Rejects startup unless the durable store is PostgreSQL. Enable it for a multi-pod deployment; SQLite is suitable only for one development or test process. The Helm high-availability preset enables it automatically.
EXTRA_CODEOWNERS_WORKER_ENABLED boolean true Runs the pull-request evaluation and authority fan-out worker in this service process. At least one worker must share the durable store.
EXTRA_CODEOWNERS_WORKER_POLL_SECONDS number 0.5 Queue poll interval in seconds; inclusive range 0.05 through 60.
EXTRA_CODEOWNERS_WORKER_LEASE_SECONDS integer 120 Job lease in seconds; inclusive range 30 through 3600. Must exceed normal evaluation time.
EXTRA_CODEOWNERS_WORKER_RETRY_MAX_SECONDS integer 60 Maximum ordinary exponential-backoff delay in seconds; inclusive range 5 through 3600. Evaluation and authority failures retry indefinitely because abandoning invalidation or reevaluation work could leave a stale success visible. A GitHub rate-limit response instead uses the provider's bounded Retry-After delay and does not advance the ordinary backoff attempt.
EXTRA_CODEOWNERS_AUTHORITY_INACCESSIBLE_RETRY_MAX_SECONDS integer 21600 Maximum delay for an authority 404 or 410 when current membership does not prove the repository is outside the installation; inclusive range 300 through 86400. The first retry waits at least five minutes and later retries back off to this ceiling. A matching authority event coalesces the row and wakes it immediately.
EXTRA_CODEOWNERS_WORKER_FOREGROUND_CONCURRENCY integer 2 Foreground evaluation consumers per process; inclusive range 1 through 16. They claim only direct webhook or operator work.
EXTRA_CODEOWNERS_WORKER_RECOVERY_CONCURRENCY integer 1 Recovery evaluation consumers per process; inclusive range 1 through 4. They take periodic work first and borrow foreground work only when recovery is empty.
EXTRA_CODEOWNERS_WORKER_AUTHORITY_CONCURRENCY integer 1 Authority fan-out consumers per process; inclusive range 1 through 4. Authority rows still block only their affected installation or repository scope.
EXTRA_CODEOWNERS_WORKER_INVALIDATION_CONCURRENCY integer 2 Exact-head invalidation consumers per process; inclusive range 2 through 4. One lane takes direct invalidations first and one takes recovery invalidations first. Each borrows the other class only when its own queue is empty.
EXTRA_CODEOWNERS_AUTHORITY_FANOUT_CONCURRENCY integer 2 Concurrent GitHub membership lookups within one authority fan-out; inclusive range 1 through 8. Keep it below the per-process GitHub request limit.
EXTRA_CODEOWNERS_WEBHOOK_INVALIDATION_TIMEOUT_SECONDS number 5.0 Inclusive range 0.1 through 8.0. Bounds both the best-effort direct-trigger GitHub API fast path and the wait that orders authority-event acceptance against an in-flight Check Run, keeping both below GitHub's 10-second response deadline. A direct-trigger fast-path timeout does not discard the queued evaluation. An authority-guard timeout prevents acceptance and returns 503 so an operator can redeliver the event.
EXTRA_CODEOWNERS_RECONCILE_ENABLED boolean true Periodically reads every visible open pull request. It queues a changed head immediately and queues an unchanged head again after its recheck deadline. Disabling it also disables automatic delivery-ID pruning.
EXTRA_CODEOWNERS_RECONCILE_INTERVAL_SECONDS integer 300 Reconciliation interval in seconds; inclusive range 60 through 86400.
EXTRA_CODEOWNERS_RECONCILE_RECHECK_SECONDS integer 900 Minimum age of a successful unchanged-head evaluation before reconciliation queues it again; inclusive range 60 through 604800. Every scan still compares GitHub's visible open-PR head, so a head change is queued immediately. A recheck of an unchanged head writes the check only when the result changes.
EXTRA_CODEOWNERS_WEBHOOK_DELIVERY_RETENTION_DAYS integer 30 Retain accepted GitHub delivery IDs for replay deduplication; inclusive range 1 through 3650 days. The elected reconciler prunes older IDs, unused finished head epochs, and stale reconciliation fingerprints on each run.

Policy and security settings

Environment variable Type Default Constraints and effect
EXTRA_CODEOWNERS_ORG_CONFIG_REPOSITORY string .github Literal repository name used for organization policy: 1–100 characters, with no / or \, and not . or ... Changing it creates a different trust-policy location and changes which repository is excluded from evaluation.
EXTRA_CODEOWNERS_POLICY_PATH string .github/extra-codeowners.toml Literal relative POSIX path used for organization and repository policy. Empty, absolute, wildcard, backslash, .-segment, and ..-segment forms are rejected. The effective path is non-delegable by default. A repository may opt only that path into normal App delegation with allow_delegation_for_policy_file = true; an organization guardrail still overrides it. Coordinate any change across both policy scopes.
EXTRA_CODEOWNERS_CHECK_NAME string Extra CODEOWNERS / approval Printable Check Run name after surrounding whitespace is removed; length 1 through 255. A change must be coordinated with every required-check rule.
EXTRA_CODEOWNERS_ALLOW_INSECURE_CHANGES boolean false When true, suppresses only the built-in non-delegable path list for every installation served by that process. It emits a startup warning and sets the insecure-mode metric to 1. Organization-added guardrails and normal delegation matching still apply.

App setup settings

Environment variable Type Default Constraints and effect
EXTRA_CODEOWNERS_SETUP_ENABLED boolean false Enables the GitHub App Manifest setup routes. Keep disabled after registration when they are not needed. In production, it may temporarily run without all three App credentials only when all three are absent; partial credentials still fail closed.
EXTRA_CODEOWNERS_SETUP_STATE_SECRET secret string or null null HMAC key for short-lived setup state. Setup-mode startup requires at least 32 UTF-8 bytes. Use a value distinct from the webhook secret.
EXTRA_CODEOWNERS_SETUP_STATE_TTL_SECONDS integer 600 Setup state lifetime in seconds; inclusive range 60 through 3600.

Do not place App private keys or webhook secrets in TOML committed to a repository. Runtime secrets belong in the deployment's secret manager.

During that credential-free bootstrap state, /health/ready reports setup_bootstrap: true and admits the pod only to serve the setup routes. It does not authenticate GitHub, accept webhooks, or evaluate pull requests. After GitHub returns the credentials, disable setup, inject the complete credential set, and restart the workload.

Loading and failure behavior

  • Repository CODEOWNERS and repository policy are read from the current target-branch commit, not from the proposed head or an older base SHA retained in PR metadata.
  • Organization policy is read from the default branch of the configured organization-policy repository (.github by default).
  • A pull request cannot grant itself authority by modifying its policy file.
  • A repository delegation that references an application alias absent from organization policy makes the combined policy invalid and produces a diagnostic failure.
  • Invalid TOML, an unsupported schema version, or ambiguous policy fails evaluation and produces a diagnostic check result. An enrolled App identity mismatch makes that App's review ineligible and emits a sanitized warning; independent appropriate human or application evidence can still satisfy the owner set.
  • A repository with no policy and no managed Extra CODEOWNERS check is not enrolled: the service publishes no check and does not load organization policy for it. Organization configuration alone never opts repositories in.
  • An explicitly disabled repository policy produces a failing check and never causes an application approval to count. If policy disappears after the App has already created its named check on the current head, a later evaluation updates that managed check to failure instead of leaving a stale success.
  • Production service startup requires an HTTPS GitHub API URL, including during the credential-free setup flow. Outside that flow it also requires complete GitHub credentials and a webhook secret of at least 32 bytes. Every non-local PostgreSQL connection must use sslmode=require; an operator-controlled loopback or Unix-socket transport is also allowed.
  • Setup-mode startup requires an HTTPS public URL and a setup-state secret of at least 32 bytes.

Safe disablement has this order:

  1. Restore GitHub's native Require review from Code Owners rule.
  2. Remove the expected-source Extra CODEOWNERS required check.
  3. Set enabled = false or remove repository policy.

A disabled file leaves a still-required gate failing. A missing required check also does not satisfy the gate.