Skip to content

docs(selfhost): document hosted/self-host migration and decommissioning - #3291

Merged
JSONbored merged 1 commit into
mainfrom
docs/selfhost-migration-and-decommission
Jul 5, 2026
Merged

docs(selfhost): document hosted/self-host migration and decommissioning#3291
JSONbored merged 1 commit into
mainfrom
docs/selfhost-migration-and-decommission

Conversation

@JSONbored

@JSONbored JSONbored commented Jul 5, 2026

Copy link
Copy Markdown
Owner

Summary

  • Adds a "Moving a repo between hosted and self-host" section to apps/gittensory-ui/src/routes/docs.maintainer-self-hosting.tsx (after the existing "How self-hosting fits with hosted docs" section). Grounded in reading src/selfhost/setup-wizard.ts and src/settings/repository-settings.ts (resolveRepositorySettings): a repo cannot be repointed between the shared hosted App and a self-host App (the wizard always mints a distinct App), settings resolve from env.DB which is a completely different database per deployment (so DB-backed settings do NOT carry over and must be re-created by hand — there is no export/import tool), while .gittensory.yml genuinely does carry over because it lives in the repo's own git history and resolveRepositorySettings overlays it identically on either side. Also documents that GitHub review-comment/check-run history is never migrated, and covers the reverse (self-host to hosted) direction the same way.
  • Adds an "Uninstalling and decommissioning" section to apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx (after "Updating and rolling back", following the same placement pattern as PR docs(selfhost): document the real update and rollback flow #3195's update/rollback section). Covers, in order: (1) revoking the GitHub App installation — confirmed there is no installation/deleted webhook handler in src/github/webhook.ts to run first, so uninstalling on GitHub's side is sufficient; (2) what happens to the named Docker volumes vs. the ./gittensory-config bind mount on stop / down / down -v (cross-checked against docker-compose.yml's actual volume declarations), with keep/export/delete options and a link to the backup/restore flow before anything destructive; (3) brokered-mode (ORB_ENROLLMENT_SECRET/ORB_BROKER_URL) deregistration — verified there is genuinely no revocation write path in this codebase (grepped every UPDATE orb_enrollments statement; none sets revoked_at outside tests), which matches the existing "Minimum broker safeguards" checklist on docs.self-hosting-github-app.tsx that already lists a revocation path as a missing prerequisite for public brokered rollout — documented honestly as unsupported today rather than implying a self-serve revoke exists; (4) removing ADMIN_GITHUB_LOGINS access — confirmed via src/auth/security.ts's isAuthorizedGitHubSessionLogin that the allowlist is re-read from env on every request (never cached, never baked into a session), so editing .env + restarting the app service is sufficient and takes effect immediately.
  • Updated this page's <head> meta description to mention uninstall/decommissioning, matching PR docs(selfhost): document the real update and rollback flow #3195's precedent of updating the meta when a page's content materially expands.
  • Advances roadmap(selfhost): production hardening and first release readiness #1819 (the self-host production-readiness roadmap). Not linked as a closing keyword: the parent issue covers backup/restore verification, release packaging, Sentry context, and Orb telemetry beyond this PR's two topics, and neither of the two sibling issues already filed against roadmap(selfhost): production hardening and first release readiness #1819 (docs(selfhost): define safe update and rollback flow #1823 update/rollback, merged; chore(migration): inventory hosted resources before self-host cleanup #1826 Cloudflare resource inventory) covers hosted/self-host migration or decommissioning — this is net-new depth work on a real, cited gap, not a specific tracked issue, consistent with how docs(selfhost): define safe update and rollback flow #1823 was scoped as its own PR earlier.

Scope decision: existing pages, not new ones

Both additions are sections within the two pages named in the task (docs.maintainer-self-hosting.tsx, docs.self-hosting-operations.tsx) rather than new dedicated routes. Justification: each topic is a few hundred words that reads naturally as a subsection of an existing page a maintainer is already on (the migration content extends the page's own "how this fits with hosted" framing; decommissioning is the natural counterpart to "Updating and rolling back" on the Operations page, which a maintainer already visits for day-two operations). Neither topic is large enough on its own to justify a new route, sidebar entry, and SECTION_LINKS wiring — that would fragment two already-small topics across even more pages for a reader to discover.

What this PR does NOT do (scope honesty)

  • Does not add a migration script or tool — there isn't one today, and the docs say so rather than implying otherwise.
  • Does not add a broker-secret revocation feature — there isn't one today (central-Orb-side, not self-host), and the docs say so rather than implying otherwise.
  • Does not touch the other roadmap(selfhost): production hardening and first release readiness #1819 sibling concerns (backup/restore verification depth, release packaging, Sentry context expansion, Orb telemetry end-to-end verification, runner load).

Scope

  • The PR title follows type(scope): short summary Conventional Commit format.
  • This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes — two files, both docs-only.
  • This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
  • I linked an issue (Advances roadmap(selfhost): production hardening and first release readiness #1819).

Validation

  • git diff --check
  • npm run actionlint — not run; no workflow files touched.
  • npm run typecheck
  • npm run test:coverage — not applicable; only apps/gittensory-ui/** changed, which Codecov does not gate (docs-only, no src/** lines changed).
  • npm run test:workers — not applicable; no Worker/backend code touched.
  • npm run build:mcp / npm run test:mcp-pack — not applicable; MCP package untouched.
  • npm run ui:openapi:check — not applicable; no API/schema changes.
  • npm run ui:lint (required npm --workspace @jsonbored/gittensory-ui run format once to fix prettier JSX-prose wrapping, then clean)
  • npm run ui:typecheck
  • npm run ui:build (confirmed both changed routes' SSR bundles built: docs.maintainer-self-hosting-*.mjs, docs.self-hosting-operations-*.mjs)
  • npm run docs:drift-check
  • npm audit --audit-level=moderate — not run standalone; npm ci reported 0 vulnerabilities and no dependency changes are in this diff.
  • New or changed behavior has unit/integration tests — not applicable; no runtime behavior changed.

If any required check was skipped, explain why:

  • This is a docs-only change confined to two files under apps/gittensory-ui/src/routes/. No src/**, scripts/**, migrations/**, or workflow files changed, so the backend/coverage/MCP/OpenAPI/audit checks don't apply. I ran every UI-specific and root check that does apply (ui:lint, ui:typecheck, ui:build, docs:drift-check, root typecheck), all green, plus git diff --check.

Safety

  • No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed. All env var names and example values are already-public placeholders used elsewhere in these docs.
  • Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
  • N/A — no auth, cookie, CORS, GitHub App, Cloudflare, or session code changes (this documents existing GitHub App/auth behavior, doesn't change it).
  • N/A — no API/OpenAPI/MCP behavior changes.
  • N/A — no new UI component/state; prose-only additions using the pages' existing DocsPage/Callout/FeatureRow/CodeBlock/Link primitives, no new components or layout.
  • UI Evidence — see below.
  • Public docs updated (this PR is entirely a docs update); CHANGELOG.md not touched.

UI Evidence

Not applicable in the screenshot-table sense — this PR is prose-only content added to two existing docs pages using their existing components (Callout, FeatureRow, CodeBlock, headings, lists, links), no new layout or visual styling. Verified via npm run ui:build (green — both changed routes' SSR bundles compiled without error) and npm run docs:drift-check (green). Did not stand up a full local preview server for this pass since the dist/server module path didn't resolve cleanly for vite preview in this sandboxed worktree; the build output already confirms both pages compile and the JSX structure (headings, <ol>/<ul>, Callout, links) matches the existing rendered pattern used by every other section on both pages.

Notes

  • Confirmed via grep that ADMIN_GITHUB_LOGINS, ORB_ENROLLMENT_SECRET, ORB_BROKER_URL, and the GitHub App manifest/permissions had zero prior mentions of migration or uninstall/decommission anywhere in the self-hosting docs before this PR, matching the audit's claim.
  • Read src/selfhost/setup-wizard.ts, src/settings/repository-settings.ts, src/orb/relay.ts, src/orb/broker.ts, src/auth/security.ts, src/github/webhook.ts, and docker-compose.yml's volumes section in full before writing, rather than restating .env.example comments verbatim.
  • Rebased onto fresh origin/main immediately before pushing (0 commits behind at push time).

@JSONbored
docs(selfhost): document hosted/self-host migration and decommissioning
eb9b3c2 
Covers two previously undocumented self-hosting topics: how to move a
repo between the hosted managed-beta App and a self-host install (what
carries over via .gittensory.yml vs. what must be re-created, since
settings live in separate databases), and how to cleanly decommission
a self-host instance (revoke the GitHub App, choose what happens to
data volumes, the current lack of a brokered-mode revocation endpoint,
and removing ADMIN_GITHUB_LOGINS access).
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Jul 5, 2026

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs		 gittensory-ui eb9b3c2 Commit Preview URL

Branch Preview URL		 Jul 05 2026, 01:03 AM

@superagent-security

superagent-security Bot commented Jul 5, 2026

Copy link
Copy Markdown
Contributor

Superagent didn't find any vulnerabilities or security issues in this PR.

@loopover-orb loopover-orb Bot added the gittensor:bug Gittensor-scored bug fix — scores a 0.05x multiplier. label Jul 5, 2026
@loopover-orb

loopover-orb Bot commented Jul 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Warning

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

⏸️ Gittensory review result - manual review recommended

Review updated: 2026-07-05 01:09:24 UTC

2 files · 1 AI reviewer · 1 blocker · readiness 93/100 · CI green · clean

⏸️ Suggested Action - Manual Review

  • Maintainer test expectations unmet — Add or update tests, or attach passing validation output that satisfies the maintainer's test expectations.

Review summary
The PR adds documentation-only guidance for moving repositories between hosted and self-host deployments and for decommissioning a self-host instance. The content is coherent with the supplied context: it distinguishes repo-local `.gittensory.yml` from DB-backed settings, warns that review/check history is not migrated, and gives destructive-volume guidance with a backup pointer. I do not see a reachable code or docs-contract defect in the visible change.

Nits — 5 non-blocking
  • apps/gittensory-ui/src/routes/docs.maintainer-self-hosting.tsx:221 says to install the self-host App first so the repo is never reviewed by nothing, but this creates an intentional overlap window; nit: tell the reader to use a test PR or a quiet window so the duplicate-review risk is bounded while they confirm the new App works.
  • apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx:625 says to suspend the installation instead of uninstalling it, but the doc does not say who can actually perform suspension in GitHub; nit: clarify whether this is available to the App owner/operator or to repo/org admins in the UI.
  • apps/gittensory-ui/src/routes/docs.maintainer-self-hosting.tsx:221: Add one sentence after the self-host install step such as `Confirm with a throwaway PR, then remove the hosted App immediately; during this overlap both Apps can receive events for new activity.`
  • apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx:625: Either point to the exact GitHub UI/API path for suspension or rephrase it as an operator-only option if ordinary installation admins cannot suspend it.
  • Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Concerns raised — review before merging

  • Maintainer test expectations unmet — Add or update tests, or attach passing validation output that satisfies the maintainer's test expectations.
Signal Result Evidence
Code review ❌ 1 blocker 1 reviewer
Linked issue ⚠️ Missing No linked issue or no-issue rationale found.
Related work ✅ No active overlap found No same-issue or scoped active PR overlap found.
Change scope ✅ 20/20 Low review scope from cached public metadata (no linked issue context).
Validation posture ✅ 25/25 PR body includes validation/test evidence.
Contributor workload ✅ 10/10 Author activity: 56 registered-repo PR(s), 46 merged, 423 issue(s).
Contributor context ✅ Confirmed Gittensor contributor JSONbored; Gittensor profile; 56 PR(s), 423 issue(s).
Gate result ❌ Blocking Repo-configured hard blocker found.
Review context
  • Author: JSONbored
  • Role context: owner (maintainer lane)
  • Public audience mode: oss maintainer
  • Lane context: Repository registration is not available in the local Gittensory cache.
  • Public profile languages: not available
  • Official Gittensor activity: 56 PR(s), 423 issue(s).
  • PR-specific overlap: none found.
Contributor next steps
  • Treat this as maintainer-lane context rather than normal contributor-lane activity.
  • Explain no-issue PR.
  • No action.
  • Link the issue being solved, or explicitly explain why this is a no-issue PR.
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

@loopover-orb loopover-orb Bot added the manual-review Gittensor contributor context label Jul 5, 2026
@JSONbored
JSONbored merged commit bf5d842 into main Jul 5, 2026
10 checks passed
@JSONbored
JSONbored deleted the docs/selfhost-migration-and-decommission branch July 5, 2026 01:17
@jimcody1995 jimcody1995 mentioned this pull request Jul 5, 2026
Merged
24 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@JSONbored JSONbored

Labels

gittensor:bug Gittensor-scored bug fix — scores a 0.05x multiplier. manual-review Gittensor contributor context

Projects

Self-Hosted Review Stack (LoopOver Orb)
Status: Done

Milestone

Maintainer auto-maintain & convergenc...

Development

Successfully merging this pull request may close these issues.

1 participant

@JSONbored