Skip to content
Cawdit

HTTP server

cawdit serve answers on the address in listen, :8080 by default. It serves plain HTTP, so put a reverse proxy with TLS in front of it when forges reach it over the internet.

Routes

Route Description
POST /webhooks/<forge> Takes the webhooks of the forge named <forge> in the deployment configuration.
GET /healthz Answers 200 while the process runs. Use it as a liveness probe.
GET /readyz Answers 200 when the server takes work: the database answers, its schema is up to date, and the workers run. It answers 503 while the server starts or drains. Use it as a readiness probe.
GET /metrics Serves the Prometheus metrics.
/api/ The dashboard’s API. It includes the sign-in routes /api/v1/auth/login, /api/v1/auth/callback and /api/v1/auth/logout, which serve the forges and the OpenID Connect provider alike. It also includes /api/v1/settings/organizations/callback, where the forge sends an owner back after they connected an organisation.
every other path The dashboard.

Keep /metrics off the public internet, for example with a rule in the reverse proxy.

Webhooks

Cawdit checks the HMAC signature of each delivery before it acts on the payload. It verifies with the secret of the repository’s owner in owner_webhook_secrets, and otherwise with the forge’s webhook_secret, as the deployment configuration explains. It reads the X-Forgejo-* headers, and the X-Gitea-* headers when those are missing. The body must be JSON and at most 1 MiB.

It acts on these events:

Event Action What Cawdit does
pull_request opened, reopened Queues a review.
pull_request synchronized Queues a review of what changed since the last review.
pull_request edited Queues a review when the edit removed the WIP: or [WIP] title prefix.
issue_comment created Hands a comment on a pull request that mentions Cawdit’s account, such as @cawdit review, to the command handler.
pull_request_comment reviewed Hands a review that only comments to the command handler, which looks for new comments that mention Cawdit. Forgejo reports a reply in an inline thread this way.

Cawdit ignores every other event, every repository whose owner is not in allowed_owners, closed pull requests, and Cawdit’s own comments. It also ignores every repository whose reviews an admin turned off in the dashboard. A review that was queued before an admin turned reviews off ends as skipped. It also applies the repository’s skip_drafts and skip_authors, which it reads from .cawdit.toml on the base branch.

A newer head commit replaces a queued review of an older one, and a redelivered webhook for the same commit is dropped as a duplicate.

The server answers each delivery with a status code and a short JSON body, which Forgejo shows in the webhook’s delivery history:

Status Meaning
202 Cawdit queued work.
200 Cawdit ignored the event, and the body says why.
400 The payload is invalid.
401 The signature is missing or wrong. Check that the forge and Cawdit use the same secret.
404 No forge has this name. Check the last segment of the webhook URL.
413 The body is larger than 1 MiB.
415 The webhook does not send application/json.
502 Cawdit could not read the repository’s settings or its own account from the forge.
503 Cawdit could not read whether it reviews the repository, or could not queue the work. Redeliver the webhook once the database is back.

Metrics

Every metric starts with cawdit_. The server also exports the standard Go and process metrics.

Metric Type Labels Description
cawdit_http_requests_total counter route, code HTTP requests by route and status code.
cawdit_http_request_duration_seconds histogram route Time to answer an HTTP request.
cawdit_webhook_intents_total counter kind, result Webhook intents handed to the queue.
cawdit_jobs gauge state Review jobs in each queue state, read from the database on every scrape.
cawdit_reviews_total counter outcome Review attempts, where each retry counts.
cawdit_review_duration_seconds histogram outcome Time a review attempt took.
cawdit_findings_total counter severity Findings posted.
cawdit_findings_suppressed_total counter none New findings dropped as duplicates of earlier ones.
cawdit_findings_fixed_total counter none Earlier findings that reviews marked fixed.
cawdit_llm_tokens_total counter model, kind Model tokens, where kind is input, output, cache_read or cache_write.
cawdit_llm_cost_usd_total counter model Known cost of model calls in US dollars.
cawdit_errors_total counter component Errors, where component is webhook, queue, review or jobs.
cawdit_webhook_syncs_total counter forge, result Webhook syncs, where result is ok, partial or failed.
cawdit_webhook_sync_duration_seconds histogram forge Time a webhook sync took.
cawdit_webhook_sync_changes_total counter forge, scope, change Webhooks the syncs changed, where scope is repository or organization and change is created, repaired or removed.
cawdit_webhook_sync_errors_total counter forge, scope Repositories and organisations a webhook sync failed for.

The route label is one of webhook, healthz, readyz, metrics, api or ui. The outcome label is reviewed, skipped or failed.

Reviews in the queue

The server keeps its review jobs in Postgres. A failed review is retried with backoff, up to 5 attempts, and each attempt may run for up to 30 minutes. A review fails at once, without a retry, when the forge answers that the pull request does not exist or that the token is not authorized.