Skip to content

REST API & GitHub App auth

miucr serve can expose a bearer-authenticated JSON REST API for queuing and reading reviews, and can authenticate to GitHub as an App installation instead of a PAT. Both are opt-in. The default webhook + PAT path (Serve & Action) is unchanged.

Set MIUCR_API_TOKEN in the environment. The default SQLite store is wired automatically. Without the token, the /v1 routes are not registered and serve stays webhook-only.

Terminal window
MIUCR_API_TOKEN=$(openssl rand -hex 32) \
WEBHOOK_SECRET=... GITHUB_TOKEN=... ANTHROPIC_API_KEY=... \
miucr serve --addr :8080 --repos owner/repo

The bearer is env-only, with no flag, so it never lands in argv, ps, or shell history.

MethodPathAuthBehavior
POST/v1/reviewsbearerQueue a review. Returns 202 and a server-generated id.
GET/v1/reviews/{id}bearerRead the stored review record.
GET/healthznoneLiveness probe.
POST/webhookHMACExisting webhook receiver.
Terminal window
curl -sS -X POST https://your-host/v1/reviews \
-H "Authorization: Bearer $MIUCR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"owner":"acme","repo":"widgets","number":42}'

The body is {owner, repo, number} (the PR number). The server:

  1. Rejects an invalid body (owner or repo empty, number not above 0) with 400.
  2. Checks the --repos allowlist. Off-allowlist is an explicit 403, unlike the webhook’s silent 200.
  3. Generates the review id. Clients never supply it.
  4. Stores a pending record, then enqueues the review on the same worker pool as the webhook.
  5. If the enqueue is rejected (queue full or job coalesced), marks the record failed and returns 503 with queue.full so the client can retry. Otherwise it returns 202 in the miucr.cli/v1 envelope:
{
"ok": true,
"api_version": "miucr.cli/v1",
"kind": "review.accepted",
"command": "reviews",
"data": { "id": "9f2c...", "status": "pending" },
"artifacts": [],
"warnings": []
}
Terminal window
curl -sS https://your-host/v1/reviews/9f2c... \
-H "Authorization: Bearer $MIUCR_API_TOKEN"

data contains only id, status, created_at, findings, and stats. The clone path and other host details are never returned. An unknown id is 404.

{
"ok": true,
"api_version": "miucr.cli/v1",
"kind": "review.result",
"command": "reviews",
"data": {
"id": "9f2c...",
"status": "done",
"created_at": "2026-06-22T07:10:00Z",
"findings": [],
"stats": {}
},
"artifacts": [],
"warnings": []
}
statusMeaning
pendingQueued, not finished. findings and stats are empty.
doneFinished. findings and stats are populated.
failedThe review errored, a stuck pending row aged past the review timeout, or the enqueue was rejected at submit time (503) so it never ran.

The worker stores the final record under the same id. If a worker crashes mid-review, a later GET that finds a pending row older than the review timeout flips it to failed, so a crash never leaves a permanent pending.

StatusWhen
400Malformed JSON, or missing owner / repo / number.
401Missing or wrong bearer, or an empty configured token.
403Repo not in --repos.
404GET of an unknown id.
405Wrong method on a /v1 route.
413Body over 64 KB.
500Internal error (token or store unavailable, id generation failed).
503Queue full or job coalesced. The record is marked failed; retry.

By default serve uses a PAT (GITHUB_TOKEN). To act as a GitHub App instead:

[github]
mode = "app"
app_id = "123456"
installation_id = "78901234"
private_key_path = "/etc/miucr/app-key.pem"
KeyRequiredNotes
modenopat (default) or app. Anything but app keeps PAT mode.
app_idyes (App)Numeric GitHub App ID.
installation_idyes (App)Numeric installation id.
private_key_pathyes (App)Path to the App private-key PEM. Never inline PEM.

miucr signs a short-lived RS256 JWT (PKCS#1 or PKCS#8 keys), exchanges it for an installation token, and caches the token in memory with a refresh about 5 minutes before expiry and one in-flight mint per installation. Installation tokens are never persisted, logged, or put in the envelope. They are lost on restart and re-minted on demand. For the multi-repo host, App accounts are configured in host.yaml: see Serve & Action.

serve is an authenticated HTTP daemon that may hold an RSA private key and mint GitHub tokens.

One bearer, one trust boundary. Anyone with MIUCR_API_TOKEN can queue reviews for any allowlisted repo and read every stored review. Treat it like a root credential for the service. Review ids are random and server-generated, so clients cannot choose or collide ids. That removes forgeable ids, not the shared-bearer scope: a holder can still read any id it learns.

Authentication

  • The bearer is env-only, like WEBHOOK_SECRET.
  • An empty configured token can never authenticate. It returns 401 before any comparison, and with no token the /v1 routes are not registered.
  • The bearer is compared in constant time. The Bearer scheme is parsed strictly and case-insensitively; an odd or partial scheme is 401.

Secrets

  • The private key is path-only. It is read at startup, parsed, and the raw PEM bytes are zeroed. It is never inline in config, logged, or in the envelope.
  • Installation tokens are in memory only.
  • The GET envelope is a whitelist, so host paths never leak. All serve error strings are redacted.

Request hardening (shared with the webhook)

  • 64 KB body cap on the JSON API (413). The webhook cap is 5 MB.
  • Method and path guards on every /v1 route (405).
  • Allowlist 403 for repos outside --repos.
  • A panic in one review is recovered on the worker and does not stop the daemon.

A live-tagged Go test exercises the real App path (mint JWT, get installation token). It is excluded from default builds and CI, and skipped unless the App env vars are set:

Terminal window
MIUCR_LIVE_APP_ID=123456 \
MIUCR_LIVE_APP_INSTALL_ID=78901234 \
MIUCR_LIVE_APP_KEY_PATH=/path/to/app-key.pem \
go test -tags live -run TestLiveAppInstallationToken ./internal/github/...

Never run it in CI, and never paste a real key, token, or bearer into a test, fixture, doc, or commit.