feat. rebuild service in Go

Rebuild the Gitea Codex review bot from the product contract with a Go HTTP service, durable SQL queue, typed Gitea client, isolated runner, and deployment updates.

Co-Authored-By: Claude <noreply@anthropic.com>

docs/webhook-setup.md

@@ -1,83 +1,53 @@
-# Webhook Setup (Global and Repository-Only)
+# Webhook setup
 
-This bot accepts Gitea webhook events at:
+The Go service accepts signed Gitea webhooks at:
 
 - `POST /webhook/gitea`
 
-It only processes these event types:
+It processes only `issue_comment` and `pull_request_comment` events. The handler verifies the exact raw request body with HMAC-SHA256 using `GITEA_WEBHOOK_SECRET`, enforces `ALLOWED_REPOS`, ignores bot-authored comments, and queues recognized `@codex` commands.
 
-- `issue_comment`
-- `pull_request_comment`
+## Configure Gitea
 
-It verifies `X-Gitea-Signature` using `GITEA_WEBHOOK_SECRET` (HMAC-SHA256).
+1. Deploy the service at a URL reachable by Gitea, for example `https://bot.example.com/webhook/gitea`.
+2. Set the same random secret in Gitea and `GITEA_WEBHOOK_SECRET`.
+3. Configure either an instance/global webhook or one repository webhook per target repository.
+4. Use JSON content type and enable only Issue comment and Pull request comment events.
+5. Add every allowed `owner/repository` to `ALLOWED_REPOS`.
+6. Test the webhook from Gitea, then check `GET /healthz`.
 
-## Prerequisites
+`WEBHOOK_MODE=global` or `WEBHOOK_MODE=repo` is a deployment label; webhook provisioning remains an administrator responsibility.
 
-1. Bot is reachable from Gitea (example: `https://bot.example.com/webhook/gitea`).
-2. `GITEA_WEBHOOK_SECRET` is set in your bot `.env`.
-3. `ALLOWED_REPOS` includes repositories you want to allow (example: `team/repo-a,team/repo-b`).
+## Environment
 
-## Option A: Global Webhook (single webhook, recommended)
+Required values are `GITEA_BASE_URL`, `GITEA_TOKEN`, `GITEA_BOT_USERNAME`, `GITEA_WEBHOOK_SECRET`, `ALLOWED_REPOS`, and either `DATABASE_URL` or the `DB_*` values. API-key Codex mode also requires `OPENAI_API_KEY`.
 
-Use this when you want one webhook configuration for many repositories.
-
-1. In Gitea, open site administration webhook settings (instance-level/global webhooks).
-2. Add a new webhook of type `Gitea` (JSON payload).
-3. Set:
-   - `Payload URL`: `https://bot.example.com/webhook/gitea`
-   - `HTTP Method`: `POST`
-   - `Secret`: same value as `GITEA_WEBHOOK_SECRET`
-   - `Content Type`: `application/json`
-4. Enable only these events:
-   - `Issue comment`
-   - `Pull request comment`
-5. Save and use the webhook test/ping action.
-6. Set `WEBHOOK_MODE=global` in bot env (informational, for deployment clarity).
-
-Notes:
-
-- The bot still enforces `ALLOWED_REPOS`; non-allowlisted repos are ignored.
-- A global webhook is usually easiest to operate at scale.
-
-## Option B: Repository-Only Webhook (per repository)
-
-Use this when you want explicit repo-by-repo control.
-
-1. Open the repository in Gitea.
-2. Go to repository `Settings` -> `Webhooks`.
-3. Add a new `Gitea` webhook.
-4. Set:
-   - `Payload URL`: `https://bot.example.com/webhook/gitea`
-   - `HTTP Method`: `POST`
-   - `Secret`: same value as `GITEA_WEBHOOK_SECRET`
-   - `Content Type`: `application/json`
-5. Enable only:
-   - `Issue comment`
-   - `Pull request comment`
-6. Save and test.
-7. Repeat for each repository.
-8. Set `WEBHOOK_MODE=repo` in bot env.
-
-Important:
-
-- This bot has one configured secret (`GITEA_WEBHOOK_SECRET`) per bot instance.
-- If multiple repo webhooks use different secrets, signature verification will fail for repos not matching the configured secret.
-
-## Minimal `.env` snippet
+The recommended local development database is SQLite:
 
 ```dotenv
-GITEA_WEBHOOK_SECRET=replace-with-random-secret
-ALLOWED_REPOS=team/repo-a,team/repo-b
-WEBHOOK_MODE=global
+DATABASE_URL=sqlite://./gitea-codex.db
 ```
 
-For repo-only mode, use `WEBHOOK_MODE=repo`.
+Production deployments should use MariaDB and a token with only the Gitea permissions needed to read pull requests/files and create comments. Keep the runner image pinned to a reviewed digest and treat review execution as untrusted code execution.
 
-## Validation Checklist
+## Command examples
 
-1. `GET /healthz` returns `{"status":"ok"}`.
-2. Webhook deliveries from Gitea return HTTP `200` (or bot returns accepted/ignored JSON, not `401`).
-3. `401 invalid signature` means webhook secret mismatch.
-4. `{"accepted": false, "reason": "repo not allowed"}` means update `ALLOWED_REPOS`.
-5. A PR comment with `@codex review` on an allowlisted repo queues a job.
+```text
+@codex review
+@codex review security
+@codex review performance --full
+@codex review tests
+@codex rerun
+@codex explain
+@codex ignore
+@codex help
+```
 
+Commands must begin the comment. Inline mentions in ordinary discussion text are intentionally ignored for compatibility. `@codex fix` is not supported.
+
+## Security notes
+
+- Invalid signatures return HTTP 401.
+- Fork pull requests are skipped unless `ALLOW_UNTRUSTED_FORKS=true`.
+- The bot launches review containers through the host Docker API; secure the Docker socket and runner host accordingly.
+- The review container receives credentials required by the configured Codex/Gitea workflow. Use least-privilege credentials, restrict network access, and do not use unpinned images in production.
+- Health detail endpoints expose bounded job metadata. Put them behind an internal network or reverse-proxy authentication if repository names and review errors are sensitive.