Adom Wiki

Correction: a webhook removes the token dependency entirely

Ray asked whether the wiki could just subscribe to a GitHub PR webhook. It can, and it is a better mechanism than what I wrote above — so disregard the "tiers 2-3 need a GitHub token" framing in the body. That was written assuming the wiki would pull PR state. With a webhook, GitHub pushes to us, and no GitHub credential is involved at all.

Verified, not assumed

• We hold admin on adom-inc/git-wiki, so a webhook can be created (gh api repos/adom-inc/git-wiki/hooks).
• There are zero webhooks on the repo today.
• wiki.adom.inc is publicly reachable — Cloudflare-fronted, GET / returns 200 — so GitHub's delivery service can POST to it.
• POST /api/webhooks/github currently returns 404. The receiver is the only missing piece.

Shape

Subscribe the repo to the pull_request event, pointed at POST /api/webhooks/github:

• Auth is a shared secret, not a token. GitHub signs each delivery with X-Hub-Signature-256 (HMAC-SHA256 of the raw body). The wiki verifies it with a secret held in its own env. Note this must be computed over the raw body before JSON parsing, and compared in constant time.
• On action: closed with pull_request.merged: true — parse pull_request.body for adom/wiki#NN, post a comment naming the PR, set status=closed. Exactly what adom-wiki issue close --comment already does internally.
• On opened / reopened / closed — record the state, which gives tier 2's status badge for free. The payload already carries everything (html_url, merged, title, state), so tier 2 needs no token either.

That collapses tiers 2 and 3 into one signature-verified endpoint. A GitHub token would only be wanted later, for backfilling PRs that predate the hook — not for steady-state operation.

Why this beats the GitHub Action alternative

The Action would have put a wiki API token into GitHub repo secrets — a credential pointing at us, held by them, usable by anyone with repo access. The webhook inverts that: GitHub holds only a shared secret that can do nothing but sign payloads, and the wiki decides what a valid payload is allowed to do. Strictly better posture, and it works for any repo we later point at the same endpoint.

Worth deciding when building

• Restrict which repos/senders are honoured, so a valid signature from an unexpected repo cannot close arbitrary issues.
• Only honour a adom/wiki#NN reference from a PR whose author is a known wiki user, or accept any — worth a deliberate call rather than a default.
• Replay/dedupe: GitHub retries failed deliveries, so closing must be idempotent (X-GitHub-Delivery is the natural key).

Closing this as not planned. We are not adding GitHub integration to the wiki: no webhook receiver, no linked-PR field, no polling of PR state.

Starting with the numbers, because the premise is checkable. adom/wiki currently holds 87 issues, of which 8 are open. That is a 91 percent close rate, and none of the 8 are fixed-but-unclosed. Every one is open for a reason: waiting on a decimation pass, on a parts-search source, on a kiosk republish, on a downstream retest, one deliberately on hold, and two filed today. The drift this proposes to fix, a tracker slowly filling with issues that were actually fixed months ago, is not occurring.

The example in the body makes the point better than the numbers do. This issue predicted that when git-wiki#271 merged, nothing would close adom/wiki#88 and someone would have to remember. #271 was merged and #88 was closed in the same working session, with the verification evidence in the closing comment, because closing an issue when its fix ships is part of how work gets finished here. The manual step that the three tiers exist to remove is a step that is being taken reliably.

Set against that: this would add a publicly reachable POST endpoint, a new shared secret to hold and rotate, signature verification over raw bodies, sender allow-listing, replay handling, and the first GitHub awareness anywhere in the codebase. That is real, permanent surface area and maintenance, bought to automate something that takes about thirty seconds and is already happening.

There is a direction reason as well, and it is the one that would still apply even if the numbers were worse. The wiki is meant to be the system of record. A bridge to GitHub does not just add coupling to a system we do not own, it relieves the pressure to close the actual gap, which is that the wiki server's source does not live here yet. The wiki already has repos, issues, and pull requests with review and merge. Solving the linkage by removing the boundary is the path we want; spanning it with a webhook makes the boundary permanent and comfortable.

None of this is a criticism of the work in this thread. The analysis was careful, and the correction reply is right that a signed webhook is better posture than a wiki API token sitting in GitHub repo secrets, since it inverts which side holds a credential pointing at the other. The notes on constant-time comparison over the raw body, restricting honoured senders, and idempotency keyed on the delivery id are the correct concerns, and that is the design we would build if we were building it. We are not, and the reason is that the problem it solves is not costing us anything measurable while the integration would.

Closing a wiki issue when its fix ships stays a manual step in the shipping checklist.