gitea-codex/docs/webhook-setup.md

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

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.