feat(selfhost): cache stable GitHub GET reads

[oktofeesh1]

Closes #1839

Summary

• Adds an auth-aware shared response cache for stable GitHub REST GETs used by Octokit and raw backfill reads.
• Single-flights cold misses and applies longer TTLs for repo/user/installation metadata and branch-protection required-status reads while excluding mutable PR/issue subresources, CI/check/status reads, pull mergeability, token minting, rate-limit, and collaborator-permission endpoints.
• Exposes Prometheus cache counters and adds panels to the self-host Grafana dashboard plus website self-host docs.

What changed

• Centralized allowlisted GitHub GET caching in src/github/client.ts, including auth/header cache keys, replay headers, cache metrics, and rate-limit-safe replay behavior.
• Routed githubJsonWithHeaders through the shared timeoutFetch path and skipped rate-limit observation writes for cache replays.
• Let the Redis response cache accept per-entry TTL overrides and preserve pagination/validator headers while rejecting non-200 cached payloads.
• Added tests for auth isolation, single-flight, raw backfill required-status cache reuse, live decision endpoint bypasses, mutable PR/issue subresource bypasses, conditional request bypasses, malformed cached headers, dashboard metrics, and fail-open cache errors.

Why

• Self-hosted webhook bursts and re-gate sweeps can repeat stable branch-protection and metadata reads and burn GitHub rate limit. This reduces duplicate calls without caching mutable review, gate, or coordination inputs.

Validation

• npm run test:ci
• npm audit --audit-level=moderate

Notes

• Issue Cache safe GitHub GETs in self-host runtime #1839 was opened immediately before this PR to track the scoped self-host GitHub GET cache work found during the rate-limit audit; there was no existing public issue for this raw-backfill plus Octokit cache boundary.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-06-30 08:33:35 UTC}

14 files · 1 AI reviewer · no blockers · readiness 60/100 · CI green · unknown

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review

Review summary
The change moves GitHub GET caching into the shared client path, narrows caching to explicit metadata and branch-protection required-status endpoints, and preserves cache isolation by auth/header keying. The visible allowlist avoids the stale PR, issue, check, status, mergeability, token, rate-limit, and collaborator-permission reads called out in the PR, and raw backfill correctly skips rate-limit observation writes only for cache replays. I do not see a diff-proven correctness break in the changed files.

Nits — 8 non-blocking

• nit: src/github/client.ts:73 labels every non-allowlisted GitHub GET bypass as class="sensitive", which makes dashboards less precise for merely unclassified endpoints.
• nit: src/github/client.ts:87 keys the cache by the raw authorization header hash, so installation-token rotation fragments otherwise stable metadata cache entries even for the same installation identity.
• nit: src/github/client.ts:120 and src/selfhost/redis-response-cache.ts:22 trust cached header strings enough to replay them; a corrupted Redis value with an invalid header value could make a cache hit throw instead of failing open.
• src/github/client.ts:73: split the bypass metric into "unclassified" versus genuinely sensitive endpoints so Grafana can distinguish intentional safety bypasses from allowlist gaps.
• src/github/client.ts:87: consider deriving the cache identity from the installation/user identity when available, while keeping the token out of the key, so metadata cache reuse survives token refreshes.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#1839
Related work	⚠️ 2 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (size label size:L; 1 linked issue).
Validation posture	❌ 5/25	Preflight is holding this PR; address the blocker before review.
Contributor workload	✅ 10/10	Author activity: 67 registered-repo PR(s), 56 merged, 7 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	oktofeesh1; Gittensor profile; 67 PR(s), 7 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: oktofeesh1
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: JavaScript, MDX, Python, TypeScript
• Official Gittensor activity: 67 PR(s), 7 issue(s).
• Related work: Items reference the same linked issue Cache safe GitHub GETs in self-host runtime #1839. (issue #1839)
• Related work: Open PR work references issue Cache safe GitHub GETs in self-host runtime #1839. (issue #1839)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Fix the blocker.
• Refresh registry data or choose a registered active repo.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[JSONbored]

Excellent, much-needed improvements. Approving.