From 5f28d82a1dccd80af12d5e66cba9148dc3b47702 Mon Sep 17 00:00:00 2001 From: JSONbored <49853598+JSONbored@users.noreply.github.com> Date: Sat, 4 Jul 2026 13:55:16 -0700 Subject: [PATCH] docs(selfhost): recommend pull vs. push relay mode, add pull-mode smoke scenario Completes the remaining #1825 deliverables that PR #3193's audit left open: a written stable-ingress-vs-pull-mode recommendation, a reproducible pull-mode smoke-test scenario alongside the existing push-mode one, and troubleshooting guidance for a failed relay registration in each mode. - GitHub App and Orb doc: new "Choosing a relay mode" section makes the existing implicit lean (pull mode for NAT/tailnet, no public ingress needed; push mode requires a real, SSRF-validated public origin) explicit, and expands the Brokered Orb env block to show ORB_RELAY_MODE. - Beta release checklist: the brokered-mode scenario now runs BOTH relay modes, since they exercise genuinely different code paths. - Troubleshooting: new guidance for selfhost_orb_relay_register_failed, covering what it means and what to check per relay mode. --- .../routes/docs.self-hosting-github-app.tsx | 34 ++++++++++++++++--- .../docs.self-hosting-release-checklist.tsx | 23 ++++++++++--- .../docs.self-hosting-troubleshooting.tsx | 28 +++++++++++++++ 3 files changed, 77 insertions(+), 8 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 7e09c865d7..ba9848e071 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 @@ -189,11 +189,37 @@ GITHUB_WEBHOOK_SECRET=`} -ORB_BROKER_URL=https://gittensory-api.aethereal.dev`} +ORB_BROKER_URL=https://gittensory-api.aethereal.dev +ORB_RELAY_MODE=pull # or omit for push (the default) -- see "Choosing a relay mode" below`} + /> + +

Choosing a relay mode: pull vs. push

+

+ Brokered mode still needs a way for GitHub webhook events to reach your self-host through + the broker. ORB_RELAY_MODE picks how: +

+ - Brokered mode is useful when the self-host should not hold a GitHub App private key. It - still needs a reachable webhook path or relay mode, depending on the network setup. + If you're not behind a stable public ingress — a home connection, a NAT without port + forwarding, a tailnet-only deployment — set ORB_RELAY_MODE=pull. It needs no + DNS record, TLS certificate, or firewall rule of its own, and tolerates a transient broker + outage more gracefully (see the release checklist's known-warnings table below). Use push + only once you already have a stable, publicly reachable HTTPS origin for this instance — the + Direct App setup wizard, for instance, always requires one anyway, so an operator running + Direct App today has it available for brokered push mode too. Before enabling this for anyone outside a controlled managed-beta cohort, weigh: (1){" "} @@ -240,7 +266,7 @@ ORB_BROKER_URL=https://gittensory-api.aethereal.dev`} 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. + brokered-mode scenario for the smoke tests that exercise both relay modes.

Webhook checks

diff --git a/apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx b/apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx index 041e704f5f..c5af0f8f11 100644 --- a/apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx +++ b/apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx @@ -71,16 +71,31 @@ SELFHOST_SMOKE_FORBID_EVENTS="selfhost_orb_export_error,selfhost_orb_relay_regis

2. Brokered mode (private / managed-beta only)

ORB_ENROLLMENT_SECRET set — the container gets tokens from the central Orb - instead of its own App key. A working push-mode registration logs{" "} - selfhost_orb_relay_register; a broken one is fatal for push mode (logged at{" "} - error, not warn). + instead of its own App key. Relay mode changes what "working" means: push mode ( + ORB_RELAY_MODE unset, the default) needs a real public{" "} + PUBLIC_API_ORIGIN and a failed registration is release-blocking (logged at{" "} + error); pull mode (ORB_RELAY_MODE=pull) needs no inbound endpoint + at all and tolerates a failed registration (logged at warn) since the drain + loop keeps retrying regardless. Run BOTH scenarios — they exercise genuinely different code + paths, not just different env (see{" "} + choosing a relay mode).

diff --git a/apps/gittensory-ui/src/routes/docs.self-hosting-troubleshooting.tsx b/apps/gittensory-ui/src/routes/docs.self-hosting-troubleshooting.tsx index 927e9e71e4..e777abb355 100644 --- a/apps/gittensory-ui/src/routes/docs.self-hosting-troubleshooting.tsx +++ b/apps/gittensory-ui/src/routes/docs.self-hosting-troubleshooting.tsx @@ -236,6 +236,34 @@ curl -X DELETE "$QDRANT_URL/collections/gittensory"`} the fastest way to confirm whether the loop is even running, before digging into the error counters.

+

+ selfhost_orb_relay_register_failed means the container could not announce + itself to the broker at boot. What it means depends on ORB_RELAY_MODE (see{" "} + choosing a relay mode): +

+
    +
  • + Push mode (default) — logged at error and{" "} + release-blocking: the container looks healthy but never receives an + event, since there is no fallback delivery path. Check that PUBLIC_API_ORIGIN{" "} + is a real, internet-reachable, TLS-terminated URL — the broker rejects a loopback or + private address at registration time, so a misconfigured or unreachable origin fails here + every time, not intermittently. +
    • +
  • + Pull mode — logged at warn and non-fatal: the drain loop ( + gittensory_orb_relay_drains_total) keeps retrying on its own schedule + regardless, so a transient failure here recovers on its own once the broker is reachable + again. A registration failure that never clears across many retries still points at{" "} + ORB_ENROLLMENT_SECRET being wrong, revoked, or not yet provisioned + server-side. +
    • +
+

+ Either mode: confirm ORB_BROKER_URL is reachable from inside the container + first — a broker that is down or unreachable produces the same registration-failed event + regardless of relay mode or credential correctness. +

AI provider circuit breaker keeps opening