Init

docs/operations.md

@@ -0,0 +1,39 @@
+# Operations Runbook
+
+## Behavior
+
+- Processes only:
+  - `pull_request` with action `opened`
+  - `pull_request_review_request` with action `review_requested` and reviewer matching bot login
+- Idempotency key: `{owner}/{repo}#{pr_number}#{head_sha}`
+- Removes bot from reviewers after a successful review post
+
+## Logging
+
+Structured logs include:
+
+- `correlation_id`
+- `owner`
+- `repo`
+- `pr_number`
+- `head_sha`
+- `outcome` (`skipped`, `success`, `failed`)
+
+Never log token values or raw authorization headers.
+
+## Failure handling
+
+- Signature validation failure: request rejected with 401.
+- Schema validation failure from Cursor output: request fails and review is not posted.
+- Invalid inline comments after validation: service posts summary review only (no inline comments).
+
+## Retry guidance
+
+- Safe to replay the same webhook delivery; dedupe blocks duplicates within TTL.
+- For transient outages (Cursor/Gitea), re-deliver webhook from Gitea UI.
+
+## Rollback
+
+1. Disable org/repo webhook.
+2. Stop deployment (`docker compose down`).
+3. Re-enable webhook after fix and redeploy (`docker compose up -d --build`).

docs/setup.md

@@ -0,0 +1,52 @@
+# Setup
+
+## 1) Create the repository and bot user
+
+1. Create `Bram/gitea-pr-review-bot`.
+2. Create the dedicated Gitea user `comedykit-pr-bot`.
+3. Create a PAT for that user with scopes:
+   - `write:repository`
+   - `write:issue`
+
+## 2) Configure secrets
+
+Create `.env` from `.env.example` and set:
+
+- `CURSOR_API_KEY`
+- `GITEA_TOKEN`
+- `GITEA_BASE_URL`
+- `GITEA_BOT_LOGIN`
+- `WEBHOOK_SECRET`
+- `PORT`
+
+## 3) Install and run locally
+
+```bash
+npm install
+npm run dev
+```
+
+Health check:
+
+```bash
+curl http://localhost:8787/healthz
+```
+
+## 4) Configure Gitea webhook
+
+Add an organization webhook for `Bram` (or per repo for pilot) with:
+
+- URL: `https://<bot-host>/webhooks/gitea`
+- Secret: matches `WEBHOOK_SECRET`
+- Events:
+  - `pull_request`
+  - `pull_request_review_request`
+
+## 5) Pilot rollout
+
+Start with:
+
+- `comedykit-frontend-new`
+- `comedykit-backend-new`
+
+After validation, enable org webhook for remaining `Bram/*` repositories and use `.gitea/pr-review-bot.yml` for per-repo opt-out.