pilot: central webhook service (user-level Gitea webhook + AI-REVIEW gate)
- pilot/webhook_server.py: stdlib HTTP receiver. HMAC-verifies X-Gitea-Signature, gates on pull_request action + AI-REVIEW label, runs review_pr in a background thread (responds 202 immediately so Gitea's delivery timeout never fires). Accepts both GitHub-style (labeled/synchronize) and Gitea event-type-style (label_updated/synchronized) action names. - pilot/ai_review.py: extract review_pr() core so both the CI run() and the webhook server share one review path. run() is now an env-driven wrapper. - pilot/README-webhook.md: architecture, onboarding, one-time per-owner user-webhook setup, the Gitea 1.26.1 system-webhook bug, the SSRF ALLOWED_HOST_LIST change, K8s deploy + script-update recipe. - README.md + design doc: note the webhook service as the preferred delivery path (partially reverses 'central webhook = non-goal', pilot only). Gitea 1.26.1 system webhooks broken (POST /admin/hooks -> 201 but never persists); user-level webhooks (one per repo-owner) are the working fallback. Gitea SSRF allow-list blocks in-cluster webhook targets by default; required a scoped [webhook] ALLOWED_HOST_LIST addition + gitea restart. E2E verified 2026-08-17: pragent-bot reviewed gitea_admin/pragent PR #2 and masi/portfolio PR #3 via the webhook service (glm-5.2:cloud). Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Marcos
@@ -0,0 +1,153 @@
|
||||
# pragent pilot — central webhook service
|
||||
|
||||
The CI-step pilot (`pilot/README.md`) needs a workflow file + secret + label per
|
||||
repo. The **central webhook service** removes the workflow file, the secret, and
|
||||
the runner dependency: a Gitea webhook posts PR events to an always-on in-cluster
|
||||
service, which gates on the `AI-REVIEW` label and runs the same review core.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
PR opened/pushed/labeled "AI-REVIEW" (any repo under a covered owner)
|
||||
│ Gitea user-level webhook (events: pull_request)
|
||||
▼
|
||||
Service pragent-webhook.pragent.svc.cluster.local (ClusterIP, ns pragent)
|
||||
│ HMAC-verify (X-Gitea-Signature) → gate: action in {opened,
|
||||
│ reopened, synchronize/synchronized, labeled/label_updated}
|
||||
│ AND pull_request.labels ∋ AI-REVIEW
|
||||
▼
|
||||
ai_review.review_pr() (same core the CI-step uses)
|
||||
1. fetch PR diff → GET gitea-http.gitea.svc:3000/api/v1/repos/{o}/{r}/pulls/{i}.diff
|
||||
2. review prompt → POST http://100.74.17.70:8789/v1/messages (glm-5.2:cloud)
|
||||
3. post review → POST .../pulls/{i}/reviews (event: COMMENT) as pragent-bot
|
||||
```
|
||||
|
||||
Fail-open, comment-only, re-posts on every qualifying trigger (no prior-comment
|
||||
synthesis yet — framework §6.1). Reviews are tagged with the head SHA.
|
||||
|
||||
## What "onboarding a repo" means now
|
||||
|
||||
1. Add `pragent-bot` as collaborator with **Write** (so it can read the diff and
|
||||
post the review). The bot stays a normal user — it is **not** a site admin.
|
||||
2. Create the `AI-REVIEW` label on the repo (one-time; `pragent-bot`'s
|
||||
`write:issue` scope can do it once it's a collaborator).
|
||||
3. Label a PR `AI-REVIEW`.
|
||||
|
||||
No workflow file, no repo secret, no act-runner needed. (The owner must already
|
||||
be covered by a user-level webhook — see below. If not, do the one-time
|
||||
per-owner setup first.)
|
||||
|
||||
## One-time per-owner setup: register a user-level webhook
|
||||
|
||||
Gitea **system webhooks** (one webhook for the whole instance — the ideal) are
|
||||
**broken in Gitea 1.26.1**: `POST /admin/hooks` returns `201` but the hook never
|
||||
persists (`GET /admin/hooks` lists 0, no delivery). So we use **user-level
|
||||
webhooks** instead — one webhook per repo-owner, which fires for every repo that
|
||||
user owns. For a small instance with few owners this is nearly as good.
|
||||
|
||||
To onboard a new owner (e.g. `masi`):
|
||||
|
||||
```bash
|
||||
# 1. generate a one-time token for that user (admin CLI, inside the gitea pod)
|
||||
K="microk8s kubectl"
|
||||
GPOD=$($K -n gitea get pod -l app=gitea --field-selector=status.phase=Running \
|
||||
-o jsonpath='{.items[?(@.status.containerStatuses[0].ready==true)].metadata.name}')
|
||||
$K -n gitea exec "$GPOD" -c gitea -- \
|
||||
gitea admin user generate-access-token --username masi \
|
||||
--scopes write:user,read:user --token-name pragent-userhook-masi
|
||||
|
||||
# 2. register the user-level webhook (events: pull_request)
|
||||
# WEBHOOK_SECRET = the shared HMAC secret in the pragent-webhook K8s Secret
|
||||
python3 - "$MASI_TOKEN" <<'PY'
|
||||
import sys, json, urllib.request
|
||||
tok = sys.argv[1]
|
||||
GAPI = "http://100.74.17.70:30000/api/v1"
|
||||
WS = open("/dev/stdin") and __import__("os").environ["WEBHOOK_SECRET"] # or paste
|
||||
req = urllib.request.Request(
|
||||
f"{GAPI}/user/hooks",
|
||||
data=json.dumps({"type":"gitea",
|
||||
"config":{"url":"http://pragent-webhook.pragent.svc.cluster.local/webhook",
|
||||
"content_type":"json","secret":WS},
|
||||
"events":["pull_request"],"active":True}).encode(),
|
||||
method="POST", headers={"Authorization":f"token {tok}","Content-Type":"application/json"})
|
||||
print(urllib.request.urlopen(req).status, urllib.request.urlopen(req).read()[:80])
|
||||
PY
|
||||
# 3. revoke the one-time token (Gitea admin UI → Users → masi → Access Tokens).
|
||||
```
|
||||
|
||||
Owners already covered: `gitea_admin` (webhook id=4), `masi` (webhook id=5).
|
||||
|
||||
## Gitea SSRF allow-list (required, one-time)
|
||||
|
||||
Gitea refuses to POST webhooks to in-cluster addresses by default:
|
||||
|
||||
```
|
||||
webhook can only call allowed HTTP servers (check your webhook.ALLOWED_HOST_LIST setting),
|
||||
deny 'pragent-webhook.pragent.svc.cluster.local(10.152.183.170:80)'
|
||||
```
|
||||
|
||||
Fix: add a scoped `[webhook]` section to Gitea's `app.ini` via the helm chart's
|
||||
inline-config secret (`gitea-inline-config`, key = section name `webhook`):
|
||||
|
||||
```ini
|
||||
ALLOWED_HOST_LIST = external,loopback,*.svc.cluster.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.64.0.0/10
|
||||
```
|
||||
|
||||
Then restart the gitea pod. Scoped to in-cluster + tailnet ranges only — not a
|
||||
blanket "allow all private". A future `helm upgrade` may overwrite the inline
|
||||
secret; bake it into `gitea.config.webhook.ALLOWED_HOST_LIST` in the helm values
|
||||
for permanence.
|
||||
|
||||
## K8s deployment
|
||||
|
||||
Manifest: `~/k8s/pragent-webhook.yaml` (Namespace `pragent`, Deployment pinned to
|
||||
`kubernets`, ClusterIP Service). The two scripts are a ConfigMap
|
||||
(`pragent-scripts`) and the webhook secret + bot token are a Secret
|
||||
(`pragent-webhook`). Verified: a regular pod on kubernets reaches both
|
||||
`100.74.17.70:8789` (headroom/glm) and `gitea-http.gitea.svc.cluster.local:3000`.
|
||||
|
||||
Update the scripts after editing `pilot/ai_review.py` or `pilot/webhook_server.py`:
|
||||
|
||||
```bash
|
||||
K="microk8s kubectl"; cd ~/Projects/pragent
|
||||
$K -n pragent create configmap pragent-scripts \
|
||||
--from-file=webhook_server.py=pilot/webhook_server.py \
|
||||
--from-file=ai_review.py=pilot/ai_review.py \
|
||||
--dry-run=client -o yaml | $K apply -f -
|
||||
$K -n pragent rollout restart deploy/pragent-webhook
|
||||
```
|
||||
|
||||
Env on the Deployment: `GITEA_API`, `OLLAMA_URL`, `OLLAMA_MODEL`, `OLLAMA_MAX_TOKENS`,
|
||||
`DIFF_MAX_CHARS` are literals; `WEBHOOK_SECRET` + `PRAGENT_BOT_TOKEN` come from the
|
||||
Secret.
|
||||
|
||||
## Relationship to the CI-step pilot
|
||||
|
||||
Both paths coexist. The webhook service is strictly less per-repo setup. For
|
||||
repos still on the CI-step workflow (`.gitea/workflows/ai-review.yml`), retire
|
||||
that file once the owner has a user-level webhook — otherwise a labeled PR gets
|
||||
reviewed twice. `gitea_admin/pragent`'s own self-CI workflow was retired when the
|
||||
webhook service went live.
|
||||
|
||||
## Known limitations (pilot, same as CI-step)
|
||||
|
||||
- Re-posts on every qualifying trigger; no prior-comment synthesis (framework §6.1).
|
||||
- No inline line comments, no status checks, no fail-close.
|
||||
- `glm-5.2:cloud` only; no tiering, no analyzer fan-out.
|
||||
- Gitea 1.26.1: system webhooks broken (see above) → user-level webhooks instead;
|
||||
hook delivery-history API (`.../hooks/{id}/tasks`) returns 404, so delivery is
|
||||
observed via the pragent-webhook pod logs (`kubectl -n pragent logs -f deploy/pragent-webhook`).
|
||||
|
||||
## Cleanup of one-time setup tokens (manual)
|
||||
|
||||
Token revocation via API/CLI is broken in Gitea 1.26.1 (`GET /users/{u}/tokens`
|
||||
401, no CLI `delete-access-token`). Revoke these one-time setup tokens in the
|
||||
Gitea admin UI (Site Administration → Users → *user* → Manage access tokens),
|
||||
name prefix `pragent-`:
|
||||
- `gitea_admin`: `pragent-syswh-reg-2026`, `pragent-syswh-list-2026`,
|
||||
`pragent-syswh-test-2026`, `pragent-syswh-retry-2026`,
|
||||
`pragent-userhook-test-2026`, `pragent-payload-look-2026`,
|
||||
`pragent-cleanup-2026`, `pragent-cleanup2-2026`, `pragent-cleanup3-2026`.
|
||||
- `masi`: `pragent-userhook-masi-2026`.
|
||||
|
||||
(Keep `pragent-bot`'s `pragent-ci` token — that's the live reviewer credential.)
|
||||
Reference in New Issue
Block a user