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`).