docs: add detailed webhook setup instructions for global and repository-only configurations

README.md

@@ -32,6 +32,10 @@ This bot is designed for self-hosted deployment:
 
 Webhook configuration is manual by design.
 
+Detailed setup instructions for both global and repository-only webhooks:
+
+- [docs/webhook-setup.md](docs/webhook-setup.md)
+
 ## Environment
 
 Use `.env.example` as template.

docs/webhook-setup.md

@@ -0,0 +1,83 @@
+# Webhook Setup (Global and Repository-Only)
+
+This bot accepts Gitea webhook events at:
+
+- `POST /webhook/gitea`
+
+It only processes these event types:
+
+- `issue_comment`
+- `pull_request_comment`
+
+It verifies `X-Gitea-Signature` using `GITEA_WEBHOOK_SECRET` (HMAC-SHA256).
+
+## Prerequisites
+
+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`).
+
+## Option A: Global Webhook (single webhook, recommended)
+
+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
+
+```dotenv
+GITEA_WEBHOOK_SECRET=replace-with-random-secret
+ALLOWED_REPOS=team/repo-a,team/repo-b
+WEBHOOK_MODE=global
+```
+
+For repo-only mode, use `WEBHOOK_MODE=repo`.
+
+## Validation Checklist
+
+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.
+