HTTP API reference¶
Extra CODEOWNERS exposes HTTP routes for GitHub and service operators. It is not a general-purpose public API. FastAPI publishes the current machine-readable schema at /api/openapi.json.
The interface is version 0.1. Paths, payloads, and error envelopes may change incompatibly before 1.0.
Routes¶
The service registers these routes:
| Method | Path | Audience | Authentication and exposure |
|---|---|---|---|
GET |
/ |
Operator or discovery client | No application authentication. Returns the product name, version, and documentation URL. |
GET |
/api/runtime-identity |
Operator or deployment verifier | No application authentication. Returns non-secret effective settings and build identity. Restrict at the network or proxy layer. |
GET |
/health/live |
Container orchestrator | No application authentication. Expose only on an operator-controlled health path. |
GET |
/health/ready |
Container orchestrator | No application authentication. Expose only on an operator-controlled health path. |
GET |
/metrics |
Prometheus-compatible scraper | No application authentication. Restrict at the network or proxy layer. |
GET |
/api/docs |
Developer or operator | Swagger UI for routes included in the OpenAPI schema. Restrict outside development environments. |
GET |
/api/openapi.json |
Documentation tooling | OpenAPI for runtime identity, the two health routes, and the GitHub webhook route. Restrict outside development environments. |
GET |
/docs/oauth2-redirect |
Swagger UI | FastAPI's OAuth redirect helper. Extra CODEOWNERS does not use end-user OAuth, but Swagger UI registers this route. |
POST |
/webhooks/github |
GitHub webhook delivery | Verifies GitHub's HMAC-SHA256 signature over the raw request body. This is the only route that requires public HTTPS ingress. |
GET |
/setup |
GitHub App administrator | Disabled by default. Returns the development App Manifest setup form when setup mode is configured. |
GET |
/setup/callback |
GitHub App Manifest callback | Disabled by default. Validates short-lived state, exchanges GitHub's one-use code, and displays the returned credentials once. |
Public webhook ingress is not a reason to expose health, metrics, documentation, or setup routes. Route them separately or protect them with an authenticating reverse proxy. The application itself does not enforce a request-rate limit, so public ingress must provide suitable abuse controls.
/, /api/runtime-identity, /health/live, /health/ready, and /metrics
return Cache-Control: no-store, max-age=0 and related defensive headers.
Access control still belongs at the network or proxy layer.
GET /¶
Success returns 200 application/json:
{
"name": "Extra CODEOWNERS",
"version": "0.1.0",
"documentation": "https://extra-codeowners.readthedocs.io/"
}
version comes from the installed package and may differ from this example.
GET /api/runtime-identity¶
Runtime identity reports the effective non-secret settings that matter to check publication. It is useful for catching a deployment pointed at the wrong App, database backend, policy path, or check name.
Success returns 200 application/json:
{
"schema_version": 1,
"environment": "production",
"github_api_url": "https://api.github.com/",
"github_app_id": 123456,
"database_backend": "postgresql",
"check_name": "Extra CODEOWNERS / approval",
"policy_path": ".github/extra-codeowners.toml",
"organization_policy_repository_name": ".github",
"application_version": "0.1.0",
"build_revision": null
}
application_version comes from the installed package. An official image
reports the full verified Git source commit baked into that image as
build_revision. A source installation reports null.
The response has no application authentication. It contains no key, webhook secret, database URL, or token, but its App ID and effective configuration are still operational metadata. Keep it on the operator route.
This endpoint is a self-report. It can show that fields agree with a deployment record, but it cannot independently prove which source a running process loaded or whether an image has trusted provenance.
GET /health/live¶
Liveness reports whether the process can serve requests and whether the worker and reconciler tasks expected in this process are still running. An orchestrator may restart the container after repeated 503 responses.
Success returns 200 application/json:
{
"status": "alive",
"worker_enabled": true,
"reconciler_enabled": true,
"worker": true,
"reconciler": true
}
worker_enabled reflects EXTRA_CODEOWNERS_WORKER_ENABLED, and
reconciler_enabled reflects EXTRA_CODEOWNERS_RECONCILE_ENABLED. The
existing worker and reconciler fields report task liveness. If an expected
task has stopped, the response is 503, status is not_alive, and its
liveness field is false.
A disabled task reports false in its *_enabled field and true in its
liveness field. A liveness field also reports true when the task is not
expected because this process has no GitHub client.
Liveness does not test GitHub credentials, database access, queue progress, or successful reconciliation. It cannot observe a worker or reconciler running in another process. Use readiness and metrics for those conditions.
GET /health/ready¶
Readiness reports whether this instance recently authenticated as the exact
configured GitHub App, can query a compatible database, and has every locally
enabled background task. A 503 response should remove the instance from
webhook traffic without forcing a restart loop.
The response is 200 when ready and 503 otherwise:
{
"status": "ready",
"github_credentials": true,
"setup_bootstrap": false,
"database": true,
"worker_enabled": true,
"reconciler_enabled": true,
"worker": true,
"reconciler": true
}
worker_enabled reflects EXTRA_CODEOWNERS_WORKER_ENABLED, and
reconciler_enabled reflects EXTRA_CODEOWNERS_RECONCILE_ENABLED. The
existing worker and reconciler fields report whether each task is ready. A
disabled task reports false in its *_enabled field and true in its
readiness field.
When built-in App setup is enabled and all three GitHub credential inputs are
absent, setup_bootstrap is true. A healthy PostgreSQL connection then makes
the setup routes reachable even though github_credentials is false. This
is a short-lived registration state: the service cannot process webhooks or
evaluate pull requests. Disable setup and restart with the complete App ID,
private key, and webhook secret as soon as GitHub returns them. A partial
credential configuration is not bootstrap mode and remains not ready.
status becomes not_ready if credentials or the database are unavailable,
or if an enabled local worker or reconciler task has stopped. This endpoint
cannot prove that a corresponding task in another process is healthy.
At startup and on a bounded interval, the service signs an App JWT and calls
GitHub's GET /app. github_credentials remains true only while the last
successful response is inside the configured freshness window and its numeric
App ID matches EXTRA_CODEOWNERS_GITHUB_APP_ID. The default probe interval is
30 seconds, and the default freshness window is 90 seconds. One failed refresh
does not discard a still-fresh success.
Readiness does not validate every installation or repository policy. Those conditions are evaluated per pull request.
GET /metrics¶
The endpoint returns Prometheus text format. Extra CODEOWNERS defines these application metrics:
| Metric | Type | Meaning |
|---|---|---|
extra_codeowners_webhooks_total |
counter | Verified GitHub deliveries, labeled by event and action. |
extra_codeowners_webhook_failures_total |
counter | Rejected or failed deliveries, labeled by reason. |
extra_codeowners_evaluations_total |
counter | Completed evaluations, labeled by conclusion. |
extra_codeowners_evaluation_seconds |
histogram | End-to-end evaluation latency, with explicit buckets through ten minutes. |
extra_codeowners_work_attempts_total |
counter | Durable worker attempts, labeled by fixed work kind, work class, and outcome. |
extra_codeowners_work_attempt_seconds |
histogram | Wall-clock duration of the same worker attempts. |
extra_codeowners_github_api_requests_total |
counter | Logical GitHub API requests, labeled by fixed operation family, authentication mode, and outcome. |
extra_codeowners_github_api_request_seconds |
histogram | Wall-clock duration of the same GitHub API requests. It includes token acquisition and a bounded rejected-token retry. |
extra_codeowners_github_api_phase_seconds |
histogram | Time in one fixed request phase, labeled by operation, authentication, work_class, and phase. Includes failed and cancelled phases; retries produce separate observations. |
extra_codeowners_github_rate_limit_events_total |
counter | GitHub rate-limit responses, labeled as installation-scoped or global. |
extra_codeowners_github_physical_requests_total |
counter | Physical request attempts, including pages and retries, labeled by fixed operation, authentication, and work_class (interactive, recovery, or authority). |
extra_codeowners_github_recovery_budget_deferrals_total |
counter | Requests deferred by the local REST core reserve, labeled by fixed operation. These requests were not sent to GitHub; a deferral is not a provider rate-limit response. |
extra_codeowners_github_pagination_endpoint_mismatches_total |
counter | Rejected pagination links whose scheme, host, port, credentials, fragment, or resource did not match the original request. The metric has no repository, pull-request, or URL labels. |
extra_codeowners_github_discovery_cache_lookups_total |
counter | Local lookups, labeled by cache (pages or compact) and result (hit or miss). A hit selects an entity validator; it still requires authenticated HTTP revalidation. |
extra_codeowners_github_discovery_cache_bytes |
gauge | Accounted storage bytes retained by this process's GitHub client, including encoded bodies where smaller, labeled by cache (pages or compact). Not total process memory. |
extra_codeowners_github_discovery_cache_entries |
gauge | Cached representations retained by the same client and cache partition. |
extra_codeowners_github_discovery_cache_events_total |
counter | Cache retention decisions, labeled by cache and fixed event: stored, expired, evicted_bytes, evicted_entries, rejected_size, rejected_metadata, rejected_encoding, skipped_no_validator, skipped_no_store, or skipped_vary. |
extra_codeowners_queue_depth |
gauge | Pending and leased exact-head invalidation, evaluation, and authority fan-out rows. |
extra_codeowners_queue_work_class_depth |
gauge | Pending durable work, labeled by fixed kind and work_class values. Use it to distinguish foreground work from recovery backlog. |
extra_codeowners_queue_work_class_oldest_age_seconds |
gauge | Age of the oldest pending row for the same fixed labels. |
extra_codeowners_queue_wait_seconds |
histogram | Time a ready work attempt waits before a worker starts it, labeled by kind and work class. Retry backoff is not included. |
extra_codeowners_webhook_to_check_completion_seconds |
histogram | Accepted work age when an evaluation finishes without a retry, labeled by work class. |
extra_codeowners_shared_head_invalidation_depth |
gauge | Exact commit generations whose durable Check Run invalidation has not finished. |
extra_codeowners_shared_head_invalidations_total |
counter | Durable exact-head invalidation attempts, labeled by completed, failed, budget_deferred, rate_limited, or superseded. A budget deferral leaves the job queued without opening provider backpressure. |
extra_codeowners_dead_jobs |
gauge | Legacy or manually introduced terminal rows. Runtime failures remain pending, so this should remain 0. |
extra_codeowners_insecure_changes_enabled |
gauge | 1 while built-in non-delegable paths are disabled; otherwise 0. |
extra_codeowners_reconciliations_total |
counter | Reconciliation outcomes, labeled with result="success", result="partial", or result="failure". A process that observes another lease owner does not increment the counter. An open provider circuit records a partial result; an election error counts as a failure. |
extra_codeowners_reconciliation_seconds |
histogram | Wall-clock duration of a reconciliation attempt, including the explicit not_elected outcome for a replica that did not own the scan lease. |
extra_codeowners_reconciliation_last_success_timestamp_seconds |
gauge | Unix timestamp of the most recent complete reconciliation by this process. A partial or failed attempt does not update it. |
extra_codeowners_reconciliation_unenrolled_skips_total |
counter | PRs omitted from recovery after GitHub confirms both missing policy at the current target-branch commit and no managed check on the head. No labels. |
extra_codeowners_trace_exports_total |
counter | Trace exporter batches, labeled by success or failure. A failure does not change the approval decision or worker retry behavior. |
Discovery responses use two disposable per-process cache partitions. Separating large discovery pages from small branch references and empty check listings prevents page churn from evicting those smaller responses. Both partitions have a one-hour idle lifetime; their combined accounted-byte cap is 32 MiB.
The request phases are authentication, semaphore_wait, quota_admission,
http, quota_accounting, retry_wait, and, for streamed responses, body. Ordinary
http timing includes reading the response body. Streamed http timing ends
when headers arrive; body covers the caller's consumption and response
closure, not just network transfer. Authentication may include a nested token
request, so adding parent and child timings double-counts that work.
The logical request span accumulates each phase across retries in
github.phase.<phase>.seconds. Discovery spans also record
github.discovery.cache (pages or compact), github.discovery.lookup
(hit, absent, or expired), and github.request.conditional for the final
physical attempt. These attributes contain no validators or request contents.
absent means no entry exists now; it does not distinguish a cold cache from
one whose entry was evicted. The cache retains no history of evicted keys.
Reconciliation trace fields¶
When tracing is enabled, each reconciliation attempt has a small independent
reconciliation.run root. Each logical GitHub operation during that attempt
has its own root, linked to the scan and searchable by
reconciliation.scan_trace_id. Nested token requests also link directly to
the scan. Worker requests outside reconciliation retain their parent-child
layout. No incoming webhook header supplies these relationships.
| Summary attribute | Meaning |
|---|---|
reconciliation.outcome |
success, partial, not_elected, failure, or cancelled. Cancellation still propagates; this is a trace outcome, not a new metric label. |
reconciliation.queued |
PRs queued by this attempt, when it returned an outcome. |
reconciliation.failed_installations |
Failed installation count, when available. |
reconciliation.lease_lost, reconciliation.stopped, reconciliation.deferred |
Final outcome flags, when available. |
reconciliation.detail_traces |
Logical request roots started in this attempt, including nested token operations. Not proof that the receiver retained them. |
reconciliation.outer_requests |
Request roots excluding nested token operations. |
reconciliation.phase.<phase>.seconds |
Totals from outer logical requests for the seven fixed phases above. Absent if that phase did not run. |
The scan's local sampling decision applies to all its detail roots, even when
the configured sample ratio is between 0 and 1. A sampled scan deliberately
omits no request span. Search all pages and compare the unique request-root
count with reconciliation.detail_traces before calling its detail complete.
Nested token phases are excluded from the summary to avoid double-counting
authentication, but concurrent outer operations can still overlap.
Source-owned scan and request traces have a fixed shape, not an unbounded
number of child spans. Their initial text attributes and private exception
fields are capped at 2,048 Unicode characters each. The affected span records
tracing.truncated_fields, including 0 when nothing was clipped. This cap
does not remove the private-metadata opt-in, constrain arbitrary external
instrumentation or operator-supplied resource attributes, or guarantee backend
delivery. Total trace volume still grows with work; use sampling to control
that volume. See the operations queries.
Discovery retry diagnostics¶
Installation-authenticated discovery GETs have one transient retry after a
one-second wait. It covers a received 500, 502, 503, or 504 without
Retry-After, or an HTTPX RemoteProtocolError, including a disconnect before
response headers. Those failures share one retry budget; a disconnect followed
by a server error does not earn another retry.
Each attempt requires authentication and shared quota admission. A disconnect
has no response headers to account for and does not refund its quota debit.
Without a known balance, the existing recovery-probe guard can defer the
retry rather than guess that quota remains. The original operation deadline
includes waiting and at most one token refresh. Waiting holds neither a
request permit nor a database transaction. Retried reads remove conditional
validators and fetch a fresh representation; an unmatched 304 fails closed.
Persistent errors still fail the operation. Other transport errors, ordinary
requests, writes, token requests and streamed reads gain no transient retry.
The existing span records github.retry_count and the wait phase. A received
server response records github.discovery.transient_retry_status_code;
a retried disconnect records the fixed
github.discovery.transient_retry_error="remote_protocol" instead. Recovered
disconnects do not export the exception message, even in private-metadata mode.
| Partition | Responses | Byte cap | Per-entry cap | Entry cap |
|---|---|---|---|---|
pages |
Repository and PR listings | 24 MiB | 1 MiB | 4,096 |
compact |
Branch references and empty managed-check listings | 8 MiB | 64 KiB | 8,192 |
The page partition uses zlib encoding when it makes a body smaller. Byte caps
and the byte gauge count retained bodies plus keys, validators, and links;
per-entry admission limits apply to the original, unencoded representation
and its metadata. Encoding cannot admit an otherwise oversized response.
Decoding is bounded by the per-entry limit. Invalid encodings are discarded
and counted as rejected_encoding; the next request fetches a fresh body.
This is local storage encoding, not HTTP content encoding or encryption.
Each page is revalidated with an authenticated conditional HTTP request before
the cached body is used. A 304 reuses the validated body and pagination links;
it still consumes a physical HTTP request and may encounter secondary limits.
The logical request counter and duration histogram use outcome="not_modified"
for that response. The physical request counter has no outcome label.
Repository metadata and open-PR listings use the fixed operation labels
repository.get and pull.list, respectively, rather than get.other.
Reconciliation resolves each distinct target branch and reads policy at its
current commit once per repository per scan. It does not use the potentially
older base SHA from the PR listing. Branch-reference requests use the fixed
operation label repository.ref and require authenticated HTTP revalidation
before a cached response is reused. A missing policy skips queueing only after
GitHub also confirms that the head has no managed check. Existing checks and present,
disabled, malformed, or unreadable policy follow ordinary evaluation.
After validating the complete list, the reconciler processes PRs in number
order and saves progress after each handled PR. A deferred attempt resumes
above that number in the unfinished repository, using a fresh GitHub listing.
Completing the repository clears its PR cursor. Earlier PRs are checked again
on the next full pass; the cursor is not evidence that their state is unchanged.
The shared REST-core budget accounts conservatively across replicas. A 304
can refund its local debit only when the accounting receipt still matches the
database row; a concurrent debit or stricter quota observation makes the
refund ineligible. This avoids crediting quota that another replica already
spent.
Prometheus also publishes generated counter and histogram series, plus Python runtime and process collectors. Metric labels must never contain repository names, pull-request titles, actor names, paths, or delivery IDs. Those values would create unbounded cardinality and disclose private repository metadata.
For a slow check, compare queue wait, worker-attempt, and GitHub API histograms
in that order. A long queue wait points to scheduling or provider backpressure;
a long worker attempt with ordinary API timing points to policy work or a
database guard. A long API family needs its phase timings to distinguish HTTP
from local coordination. When OTLP
tracing is enabled, use the sampled trace_id in the corresponding structured
logs to inspect the same operation without adding private values to Prometheus.
success means the elected process finished its resumed scan of every visible,
unsuspended installation and validated the repository and PR listings returned
by GitHub. PRs below a saved resume point were handled in an earlier attempt,
not rechecked in this one. partial means the process lost its lease or could not
safely scan at least one installation or queue its pull requests. If graceful
shutdown interrupts an elected attempt, that attempt is also partial and does
not advance the last-success timestamp. An idle or unelected shutdown records
no attempt.
Per-installation failures include GitHub request errors, malformed payloads,
and database errors while adding queue jobs. Work queued before that failure
remains durable, and the scan continues with later installations while it
still owns the lease. failure means the attempt stopped before it could
return a scan result. This includes a malformed top-level installation list;
the service validates that whole list before processing any installation.
Reconciliation accepts installation IDs and pull-request numbers only as
positive JSON integers. It rejects booleans, strings, nulls, zero, and negative
values. suspended_at must be null or a timezone-aware ISO 8601 timestamp, and
archived must be a JSON boolean. Every open pull request must contain an
object-valued head with a full 40- or 64-character lowercase hexadecimal
commit ID. Field-level validation failures log a fixed reason code and omit the
rejected value. If GitHub returns something other than the expected list or
includes a non-object item, the client rejects it before field validation. The
service then logs a fixed reconciliation event and error template; it still
omits the rejected value.
The last-success gauge belongs to one service process. For a deployment with several replicas, alert on the newest value across all replicas.
POST /webhooks/github¶
GitHub sends a JSON body with these headers:
| Header | Constraint and purpose |
|---|---|
X-Hub-Signature-256 |
Required sha256=... HMAC signature. The service compares it with a digest of the exact raw body and the configured webhook secret. |
X-GitHub-Event |
Required event name, at most 128 characters. It selects the scheduling handler. |
X-GitHub-Delivery |
Required delivery ID, at most 128 characters. Retained mapped events use it for replay-safe deduplication. |
The service verifies the signature before parsing JSON. The JSON root must be an object, and action, when present, must be a string. An authenticated mapped delivery is recorded in the same database transaction as its evaluation or authority fan-out work.
For a direct pull-request, review, or rerequest trigger, the signed payload must
identify the head as exactly 40 or 64 lowercase ASCII hexadecimal characters.
Ingress advances that head's shared generation and makes its exact-head
invalidation pending in the same transaction as the delivery and pull-request
job. The delivery stores that exact generation token. A malformed identifier
returns 400; the service does not create a partial fence.
Ingress then makes one bounded attempt to fetch the current pull request. It
updates an existing managed check on the accepted head to completed with
conclusion failure. It
creates one only when that head is still current on an open pull request and
repository policy exists. A historical head with no managed check is skipped.
If the pull request already moved, ingress records separate durable work for
the live head.
Every newly accepted direct delivery attempts fast invalidation. A retained duplicate retries that path only when an earlier invalidation remains pending; the accepted head and its stored shared-generation token do not change. If the retry discovers that the pull request now points to a different head, it separately advances the live head's shared and evaluation generations and queues that head for invalidation.
Full evaluation happens asynchronously. A 202 response for a mapped trigger means the service stored durable work, not that the pull request passed or that the fast-path Check Run update reached GitHub.
202 response field |
Meaning |
|---|---|
accepted |
true if this request recorded the mapped delivery. An already retained delivery returns false. Unmapped deliveries return true because they are acknowledged but not retained. |
queued |
true when this request accepted new mapped work, its duplicate fast-path attempt reset a check, or that attempt separately queued a newly observed live head. This field is not a live queue-depth check. |
For example, a duplicate direct pull-request delivery may return
{"accepted":false,"queued":true} after resetting its accepted head or
discovering and queuing a newer live head. The retained delivery still refers
to its original head and generation. Other duplicate mapped deliveries leave
existing work unchanged. Once retention pruning removes a delivery ID,
redelivery can create or coalesce new work, but workers still fetch current
GitHub evidence.
An authenticated event or action with no mapping returns {"accepted":true,"queued":false}. It is neither retained nor deduplicated. Pull-request work for the configured organization-policy repository is handled this way because that repository stays under native human enforcement.
The following policy-source and repository-lifecycle events are retained as installation-wide fan-out work:
- a relevant organization-policy push to its default branch
- an organization-policy repository deletion, rename, transfer, or default-branch change
- a target-repository rename, transfer, or unarchive
- removal of the configured organization-policy repository from App selection
- missing or malformed
repositories_removedevidence, which is treated as possible loss of the policy source.
A well-formed removal containing only ordinary target repositories is acknowledged without work because the App has already lost access.
Webhook failure responses¶
Webhook failures use these status codes:
| Condition | Status | Result |
|---|---|---|
Missing or malformed X-Hub-Signature-256, or a signature mismatch |
401 |
Reject before parsing JSON. |
Missing or overlong delivery or event header; invalid Content-Length; malformed JSON; non-object JSON; invalid payload for a mapped event |
400 |
Reject the request. |
| Body larger than 10 MiB | 413 |
Reject whether or not Content-Length is present. The service enforces the limit while streaming; ingress should enforce the same limit. |
| No configured webhook secret | 503 |
Reject because the receiver is not configured. |
| Retained direct trigger with no configured evaluator | 503 |
Store the trigger, but report that synchronous check revocation is unavailable. |
| Database failure while accepting mapped work | 503 |
Do not acknowledge successful ingestion. |
| Timeout or database failure while ordering an authority event against an in-flight Check Run | 503 |
Do not record the delivery. Restore the service, then use GitHub's Redeliver control. GitHub does not retry automatically. |
After durable acceptance of a direct trigger, a GitHub API error or expiry of
EXTRA_CODEOWNERS_WEBHOOK_INVALIDATION_TIMEOUT_SECONDS leaves exact-head
invalidation pending and still returns 202. The durable invalidation worker
resets an existing managed check and fans out evaluation to current open pull
requests on that commit. Manual redelivery can retry the fast path.
Authority acceptance uses the same timeout to wait for an in-flight final Check Run under the installation publication guard. Its transaction advances a persistent installation authority epoch and records fan-out. Every evaluation row records the epoch current when it was enqueued, so work from before the authority change cannot publish even after fan-out finishes.
The authority worker then:
- Splits installation-wide work into repository fences when needed.
- Lists affected open pull requests.
- Supersedes each evaluation generation.
- Makes a bounded attempt to invalidate each managed check.
Installation-wide work is claimed first, followed by repository work blocking direct events. Among other jobs, batches covering every base precede targeted branch batches. Each repository has one discovery job with up to 100 target branches sharing its listing. Overflow broadens the batch to every base. Pushes received during a scan collect in one later batch without restarting the current pass. The shared fence blocks publication for the repository, including queued PRs outside the selected branches.
Exact-head invalidation, evaluation, and authority failures remain pending and retry indefinitely with bounded ordinary backoff. GitHub rate limits use a separately bounded provider delay. GitHub requires webhook responses within 10 seconds and does not automatically redeliver failed deliveries, so synchronous work is bounded. A direct-trigger fast-path failure does not undo durable acceptance; an authority-guard timeout prevents acceptance and requires redelivery.
GitHub describes its signature contract in Validating webhook deliveries.
App Manifest setup routes¶
Setup mode requires all three settings:
EXTRA_CODEOWNERS_SETUP_ENABLED=true- an HTTPS
EXTRA_CODEOWNERS_PUBLIC_URLthat contains only an origin EXTRA_CODEOWNERS_SETUP_STATE_SECRETcontaining at least 32 bytes.
When setup is disabled, both setup routes return 404 and the other two
settings are optional. When setup is enabled, missing or invalid setup settings
prevent configuration from loading. A production setup deployment may omit all
three App credentials only while it is in bootstrap mode; a partial credential
configuration still fails closed. The setup-state secret signs the short-lived
setup exchange and is separate from the webhook secret.
GET /setup¶
The optional organization query parameter selects where GitHub creates the App. With a value, the form targets that organization's App settings. Without it, the form targets the administrator's personal App settings.
The route returns 200 text/html, or 404 when setup is disabled. Its response includes no-store, no-referrer, content-type, and restrictive content-security headers.
GET /setup/callback¶
GitHub redirects the one-use code and signed state query parameters to this route. Both are required. The service validates the state's signature, audience, and expiry before exchanging the code, then displays the complete App Manifest conversion response with no-store headers.
The response contains the App ID and secret credential material:
- the private key
- the webhook secret
- any client secret returned by GitHub.
Callback outcomes use these status codes:
| Condition | Status |
|---|---|
| Successful exchange | 200 text/html |
| Invalid or expired state, rejected exchange, or incomplete credential response | 400 |
Missing code or state |
422 |
| Setup disabled, with both required query parameters present | 404 |
The service does not retain the returned credentials. Copy them directly into a secret manager before closing the page. The callback query and result must not appear in proxy access logs, screenshots, browser synchronization, support tickets, terminal transcripts, or logs.
Manifest defaults¶
The setup flow creates a private App with these permissions:
| Permission | Access |
|---|---|
| Checks | Write |
Commit statuses (statuses) |
Write |
| Contents | Read |
| Metadata | Read |
| Members | Read |
| Pull requests | Read |
Commit statuses makes the App selectable as an expected source in organization-level rulesets. Runtime installation tokens omit statuses. The GitHub permissions reference lists the explicit subscriptions and the automatically delivered installation events.
Keep setup mode disabled when operators do not register Apps through this service.
Errors, retries, and compatibility¶
Clients must use HTTP status codes rather than matching response text. The JSON error envelope and OpenAPI compatibility policy may change before 1.0; release notes will identify those changes.
Mapped webhook deliveries are idempotent while their delivery IDs remain in the deduplication table. The service does not offer client-controlled retries, pagination, or an HTTP version-negotiation header.