pr-reviewer/docs/operations.md

Operations Runbook

Behavior

• Processes only:
  • pull_request with action opened
  • pull_request or 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).