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

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