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.