From 4df8a96a37b4d239f47e88bc969d829358706ba8 Mon Sep 17 00:00:00 2001 From: JSONbored <49853598+JSONbored@users.noreply.github.com> Date: Thu, 2 Jul 2026 18:31:38 -0700 Subject: [PATCH 1/3] docs(orb): separate telemetry from token brokerage (#1939) The GitHub App and Orb doc presented direct App and brokered Orb as symmetric, co-equal options with no risk framing, no explicit "private/managed-beta only" label on brokered mode, and no explanation that telemetry export is a completely separate concern from token brokerage -- exactly the conflation #1939 asks to resolve. - Direct App is now explicitly labeled the recommended default; brokered Orb is explicitly labeled private/managed-beta only, with a callout on why (every brokered install draws on gittensory's own GitHub API quota, not just the operator's). - New "Telemetry is separate from token brokerage" section: telemetry export is always-on in EITHER connection mode (it's what feeds the homepage counters and cross-fleet gate calibration), while brokerage is the optional, restricted piece. Documents exactly what is/isn't exported and the ORB_AIR_GAP opt-out. - New "Brokered mode operational risks" callout: rate-limit blast radius, quota management, support burden, abuse/misconfiguration risk. - New "Minimum broker safeguards before a public rollout" maintainer checklist: enrollment quota, per-install concurrency, per-install rate budget, revocation path, metrics broken out by enrollment. --- .../routes/docs.self-hosting-github-app.tsx | 98 +++++++++++++++++-- 1 file changed, 91 insertions(+), 7 deletions(-) diff --git a/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx b/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx index 59f4913ddf..33b5000bce 100644 --- a/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx +++ b/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx @@ -10,13 +10,13 @@ export const Route = createFileRoute("/docs/self-hosting-github-app")({ { name: "description", content: - "Connect a self-hosted Gittensory review service to GitHub with a direct GitHub App or brokered Orb enrollment.", + "Connect a self-hosted Gittensory review service to GitHub with your own direct GitHub App (the default, recommended path) or private managed-beta brokered Orb enrollment.", }, { property: "og:title", content: "Self-host GitHub App and Orb — Gittensory docs" }, { property: "og:description", content: - "Connect a self-hosted Gittensory review service to GitHub with a direct GitHub App or brokered Orb enrollment.", + "Connect a self-hosted Gittensory review service to GitHub with your own direct GitHub App (the default, recommended path) or private managed-beta brokered Orb enrollment.", }, { property: "og:url", content: "/docs/self-hosting-github-app" }, ], @@ -30,23 +30,30 @@ function SelfHostingGithubApp() {

Choose a connection mode

+ + Direct App mode is the public default: it costs gittensory nothing to support and can't + overrun a shared rate-limit budget. Brokered mode routes every token mint through + gittensory's own infrastructure and GitHub API quota — every external brokered install is + gittensory's rate-limit and reliability problem, not just the operator's, so it stays + private/managed-beta until the safeguards below are in place. +

One-click App creation (recommended for a Direct App)

@@ -105,6 +112,36 @@ GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github-app-private-key.pem GITHUB_WEBHOOK_SECRET=`} /> +

Telemetry is separate from token brokerage

+

+ These are two independent things people conflate because they're both "Orb": anonymized + fleet-calibration telemetry export (always on, works in either connection + mode) and token brokerage (optional, private/managed-beta only, lets your + self-host get installation tokens from gittensory instead of holding its own App key). + Choosing Direct App mode does not opt you out of telemetry, and it's what makes{" "} + the homepage counters and cross-fleet gate calibration reflect direct + installs, not just brokered ones. +

+ +

Brokered Orb env

+ + Before enabling this for anyone outside a controlled managed-beta cohort, weigh: (1){" "} + rate-limit blast radius — every brokered install's GitHub API traffic draws + from token pools gittensory manages, so one misbehaving or high-volume install can degrade + every other brokered install; (2) quota management — there is no automatic + per-install cap on how much of that shared budget one enrollment can consume; (3){" "} + support burden — a broken brokered install looks like a gittensory outage + to its operator, not a self-host misconfiguration, and lands as a support request on + gittensory directly; (4) abuse/misconfiguration risk — an enrollment secret + that leaks or a misconfigured relay can mint tokens or receive webhook traffic for repos the + intended operator doesn't control. + + +

Minimum broker safeguards before a public rollout

+

+ A maintainer go/no-go checklist — do not open brokered enrollment beyond a small, known, + controlled cohort until every item below is true: +

+
    +
  • + Enrollment quota — a hard cap on how many brokered installs can be active + at once, not just an informal agreement. +
    • +
  • + Per-install concurrency limit — one brokered install cannot occupy an + unbounded share of the token-minting or webhook-relay pipeline. +
    • +
  • + Per-install rate budget — a ceiling on GitHub API calls attributable to a + single enrollment, independent of the other installs sharing the broker. +
    • +
  • + Revocation path — an enrollment secret can be revoked immediately, + without waiting for a deploy, when it's compromised or the install is abusive. +
    • +
  • + Metrics broken out by enrollment — token-mint volume, webhook-relay + volume, and error rate are visible per-enrollment, not only aggregated across every + brokered install, so one bad actor is identifiable instead of hiding in the average. +
    • +
+

+ See Troubleshooting for what a degraded + brokered relay looks like in logs today, and{" "} + the beta release checklist's + brokered-mode scenario for the smoke test that exercises this path. +

Webhook checks

Date: Thu, 2 Jul 2026 18:37:15 -0700 Subject: [PATCH 2/3] docs(orb): fix "always on" vs. air-gap-opt-out wording contradiction Gate review nit: "always on" read as contradicting the ORB_AIR_GAP opt-out documented two paragraphs later. "Enabled by default" says the same thing without the apparent contradiction. --- .../src/routes/docs.self-hosting-github-app.tsx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx b/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx index 33b5000bce..19f2c2d3c1 100644 --- a/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx +++ b/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx @@ -115,10 +115,10 @@ GITHUB_WEBHOOK_SECRET=`}

Telemetry is separate from token brokerage

These are two independent things people conflate because they're both "Orb": anonymized - fleet-calibration telemetry export (always on, works in either connection - mode) and token brokerage (optional, private/managed-beta only, lets your - self-host get installation tokens from gittensory instead of holding its own App key). - Choosing Direct App mode does not opt you out of telemetry, and it's what makes{" "} + fleet-calibration telemetry export (enabled by default, works in either + connection mode) and token brokerage (optional, private/managed-beta only, + lets your self-host get installation tokens from gittensory instead of holding its own App + key). Choosing Direct App mode does not opt you out of telemetry, and it's what makes{" "} the homepage counters and cross-fleet gate calibration reflect direct installs, not just brokered ones.

From fe57e1761daa5ca7d43ad505983ea55543f8dfd9 Mon Sep 17 00:00:00 2001 From: JSONbored <49853598+JSONbored@users.noreply.github.com> Date: Thu, 2 Jul 2026 18:47:04 -0700 Subject: [PATCH 3/3] docs(orb): standardize on private/managed-beta spelling throughout the page --- .../gittensory-ui/src/routes/docs.self-hosting-github-app.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx b/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx index 19f2c2d3c1..b309db729d 100644 --- a/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx +++ b/apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx @@ -30,7 +30,7 @@ function SelfHostingGithubApp() {

Choose a connection mode