Self-hosted reviews
Run the Gittensory review service on your own infrastructure, with your own data store, GitHub App, AI provider, enrichment service, observability, and private repo policy.
What this section covers
Self-hosting is a major product path, not a single install command. The service can run as a quiet advisory reviewer, a private maintainer copilot, or a full review operator. The docs are split by operating concern so you can onboard gradually.
- Core service
- The same review engine as the hosted Worker, served from a Node container with self-host adapters for data, queue, cron, metrics, and webhooks.
- Private policy
- A mounted GITTENSORY_REPO_CONFIG_DIR lets maintainers keep review thresholds, autonomy, and notes out of public repos.
- Optional intelligence
- AI, RAG, and REES are additive. Each has its own enablement switch, prerequisites, and fail-safe behavior.
- Operator control
- Dry-run, advisory, and live modes let you phase in behavior without exposing contributors to unfinished automation.
Recommended reading order
- Start with Quickstart to get a local instance healthy.
- Read Configuration before enabling repo review features.
- Set up GitHub App and Orb so webhooks and installation tokens are correct.
- Add AI providers, REES enrichment, the REES analyzer reference, and RAG indexing only after the deterministic path is stable.
- Use Operations, Backup and scaling, and Security before exposing the service to production traffic.
- Run the release checklist before tagging or promoting a candidate image.
Pages
Bring up the container, smoke-test readiness, and confirm the GitHub webhook path.
Understand env vars, private repo config, feature flags, and safe baseline defaults.
Choose a direct GitHub App or brokered Orb enrollment and set the right permissions.
Wire Anthropic, OpenAI-compatible, Ollama, Claude Code, or Codex safely.
Run external analyzers, configure REES_ANALYZERS, and understand where results show up.
Review every analyzer name, input, finding shape, network call, and token requirement.
Configure embeddings, Qdrant, indexing jobs, and cold-index behavior.
Health checks, logs, metrics, dashboards, jobs, queues, and daily operator routines.
SQLite, Litestream, Postgres, Redis, restores, and multi-instance tradeoffs.
Official images, tags, source maps, upgrade cadence, and local custom builds.
Versioning, the smoke matrix, an image-contents audit, and release notes for an orb-vX.Y.Z release.
Secret handling, private policy, public output boundaries, network exposure, and auth.
Review not firing, REES silent, AI unavailable, RAG empty, queue stuck, and webhook failures.
How self-hosting fits with hosted docs
The hosted maintainer workflow still applies: review modes, gate settings, safety rules, and privacy boundaries are the same concepts. Self-hosting adds infrastructure choices, deployment secrets, private config, and local operating responsibility. Use Tuning your reviews for gate semantics and this section for running the service yourself.
Moving a repo between hosted and self-host
"Hosted" here means the private managed-beta shared gittensory App described in GitHub App configuration — a repo installed there is reviewed by gittensory's own cloud Worker and its own database. "Self-host" means your own container from Quickstart, with its own GitHub App (or brokered Orb enrollment) and its own data store. There is no automated migration path between the two today — moving a repo is a manual App swap plus re-creating whatever settings you had, not a toggle.
Switching a repo from hosted to self-host
- Stand up your self-host instance first and confirm
/readyis healthy — see Quickstart — before touching the hosted install, so the repo is never briefly reviewed by nothing. - Create your own GitHub App via the self-host setup wizard (or brokered Orb enrollment). You cannot repoint the existing shared hosted App at your self-host container — the shared App's credentials belong to gittensory's cloud Worker, and
src/selfhost/setup-wizard.tsalways mints a distinct App tied to your instance's own webhook URL. - Install your new self-host App on the repo, choosing only that repo (or the org, if you're migrating several at once).
- Uninstall the shared hosted App from that repo (repo Settings → Integrations → GitHub Apps → gittensory → Uninstall, or the equivalent org-level App settings page) once you've confirmed the self-host App is reviewing PRs correctly. Leaving both installed means two reviewers post competing checks and comments on the same PRs.
What does not carry over automatically
Hosted-side settings live in gittensory's own cloud database, keyed by repo full name — resolveRepositorySettings (src/settings/repository-settings.ts) reads them from env.DB, which is a completely different database instance than your self-host container's. A self-host instance has no access to, and no import path for, whatever thresholds, gate modes, or review-mode settings you configured on the hosted side through the control panel or API. If you want the same behavior, you have to re-configure it on the new instance from scratch — there is no export/import tool for this today.
One thing genuinely does carry over: a repo's own .gittensory.yml (config-as-code), because it lives in the repository's git history, not in either service's database. resolveRepositorySettings overlays it on top of whatever DB settings exist, on either hosted or self-host — so gate-mode overrides, thresholds, and other settings expressed in that file apply identically the moment the new App starts reviewing, with nothing to re-enter.
What stays identical for contributors either way: the review still posts as a gittensory[bot]-style comment (under your own App's slug once you migrate, not literally gittensory[bot]) plus the same check-run shape, and the gate semantics in Tuning your reviews and How reviews work are unchanged — only the infrastructure and the settings storage location differ.
Switching a repo from self-host back to hosted
The reverse migration has the same shape and the same gap: uninstall your self-host App from the repo, install the shared hosted App (if you have managed-beta access — see GitHub App configuration), and re-create any DB-backed settings on the hosted side. .gittensory.yml again carries over for free since it travels with the repo; nothing else does. Your self-host instance's data volumes are untouched by this — see Uninstalling and decommissioning if you also intend to shut the instance down rather than keep it idle or reuse it for other repos.