pragent/pilot/README-webhook.md

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):

# 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):

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:

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