Files

T

Marcos 8758b22802 docs: techspark user webhook (id=6) + org-webhook note + cleanup token

Co-Authored-By: Claude <noreply@anthropic.com>

2026-08-17 20:38:14 +00:00

9.4 KiB

Raw Blame History

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 existing reviews → dedupe: skip if a review already carries
      <!-- pragent:sha=<this sha> -->  (no duplicate on label-toggle / re-fire)
   2. fetch PR diff     → GET .../pulls/{i}.diff
   3. fetch .pr-review.json @ head ref (optional repo-local focus/config)
   4. prior review bodies → fed as "already said" context (light §6.1)
   5. review prompt     → POST http://100.74.17.70:8789/v1/messages  (glm-5.2:cloud)
      model emits JSON: {findings:[{severity,path,line,problem,fix,suggestion}]}
   6. parse diff hunks → valid (path, new_line) anchors (RIGHT side)
   7. post review       → POST .../pulls/{i}/reviews  (event: COMMENT) as pragent-bot
      - anchored findings → inline line comments, body wraps `suggestion` in a
        ```suggestion fence (Gitea renders an apply-button)
      - unanchored findings → summary-body bullets
      - summary body carries the <!-- pragent:sha=... --> marker for dedupe

Fail-open. No duplicate per commit (dedupe). Inline comments + apply-able suggestions where the line anchors cleanly. Repo-local focus via .pr-review.json. Prior reviews fed as context so re-pushes synthesize instead of repeating (light version of framework §6.1).

What "onboarding a repo" means now

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.
Create the AI-REVIEW label on the repo (one-time; pragent-bot's write:issue scope can do it once it's a collaborator).
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.)

Repo-local focus: `.pr-review.json` (optional)

Drop a .pr-review.json at the repo root (committed on the PR's branch, or on the default branch) to steer the review for that repo. All fields optional; absent file = defaults. JSON (stdlib, no YAML dependency).

{
  "focus": ["security", "supply-chain", "sql-injection"],
  "exclude_paths": ["vendor/**", "**/*.generated.ts"],
  "languages": ["typescript", "go"],
  "instructions": "We use Result<T,E> for error handling. Flag any bare throw. Flag eval()/exec() on user input as critical."
}

focus — weight these review areas higher (does not blind the reviewer to critical issues outside them).
exclude_paths — tell the model to ignore these paths.
languages — hint the primary languages.
instructions — free-form house conventions / compliance language.

Fetched at review time from the PR head ref (GET /repos/{o}/{r}/contents/.pr-review.json?ref=<head sha>). Bad/missing file fails open to defaults. The bot's read:repository scope reads it.

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), techspark (webhook id=6 — a user account, not an org; covers techspark/suaspark-site, techspark/spark-ui, etc.). True orgs need org-level webhooks (POST /orgs/{org}/hooks, requires a token with write:organization).

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)

One model (glm-5.2:cloud); no tiering, no analyzer fan-out, no shared-prefix caching. Those are framework features.
No status checks, no fail-close (review never blocks a PR).
Dedupe is per-commit: a re-push (new SHA) always re-reviews (by design — the diff changed). Prior-review context is fed to the model so it doesn't repeat, but the bot does not delete or resolve its own old reviews.
Inline comments only anchor to post-change lines present in the diff (context + added). A finding whose line the model places on a removed line or outside the diff is folded into the summary as a bullet instead of misplaced.
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.
techspark: pragent-userhook-techspark-2026.

(Keep pragent-bot's pragent-ci token — that's the live reviewer credential.)

9.4 KiB Raw Blame History