84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
# 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.
|
|
|