Tuning your reviews

How configuration fits together

Gittensory review is the engine that scores, gates, and comments on your pull requests. You shape its behavior in two places, and you never have to touch the review algorithm itself:

• Per-repo settings — gate modes, score thresholds, guardrails, and which surfaces are enabled. Set them in the dashboard, or declare them as config-as-code in a .gittensory.yml file in the repo.
• Feature flags — the GITTENSORY_REVIEW_* family of environment variables on the worker. These switch whole capabilities (safety scanning, grounding, RAG context, the unified comment, the content lane, observability, self-tuning, and more) on or off for the deployment.

The review algorithm — the deterministic gate, the scoring signals, the slop detector, the grounding and RAG context builders, and the comment renderer — is open source. Anyone can read exactly how a verdict is reached. The settings above sit on top of that open algorithm and never reveal review direction, so a contributor cannot read them and game the gate.

Precedence

Most specific wins:

• .gittensory.yml in the repo, then
• per-repo database settings, then
• built-in safe defaults.

Path holds are explicit config-as-code only: omitted or empty settings.hardGuardrailGlobs means no path guardrails, not a hidden engine fallback.

The friendly gate: block in .gittensory.yml is a typed alias for the gate-related fields and wins over the generic settings: block for those same fields. Gittensory looks for the manifest at the first match of .gittensory.yml → .github/gittensory.yml → .gittensory.json → .github/gittensory.json.

Feature flags (GITTENSORY_REVIEW_*)

These are worker environment variables, every one defaulting to OFF. "Truthy" means one of 1, true, yes, or on (case-insensitive); anything else — including unset, empty, or false — is OFF. When a flag is OFF its code path is inert: the review behaves exactly as if the feature did not exist.

One flag is a scope rather than a capability: GITTENSORY_REVIEW_REPOS is a per-repo allowlist that must also pass for any per-PR feature to run on a given repo. So a per-PR feature activates only when its own flag is ON and the repo is allowlisted.

• GITTENSORY_REVIEW_REPOS — the per-repo allowlist. Comma-separated owner/repo names that may run the per-PR features (safety, grounding, RAG, reputation, unified comment). Empty or unset means no repos — every per-PR feature stays dormant for everyone regardless of the global flags. Case-insensitive and trimmed; stray commas are ignored. The cron and endpoint flags (ops, self-tune, parity audit, content lane, draft) are not scoped by this list.
• GITTENSORY_REVIEW_SAFETY — safety scan in the review path: it neutralizes prompt-injection in untrusted PR title/body/diff before the AI reviewer sees it, and scans the diff for leaked secrets, surfacing a secret_leak blocker. Per-PR (also needs the repo in the allowlist).
• GITTENSORY_REVIEW_GROUNDING — grounds the AI reviewer with the PR's finished CI status plus the full post-change content of the changed files, so the model verifies claims against reality instead of predicting CI or flagging symbols defined just outside the diff hunk. Per-PR.
• GITTENSORY_REVIEW_RAG — retrieval-augmented context: queries the codebase vector index for related code and docs (callers, related modules, existing conventions) and appends a "Relevant existing code / docs" section to the reviewer prompt. Additive only. Inert until a vector index exists for the repo — a cold or missing index degrades to no context. Per-PR.
• GITTENSORY_REVIEW_REPUTATION — submitter-reputation spend control. A new, burst, or low-reputation submitter is downgraded to a deterministic-only review; good reputation proceeds normally. Never surfaced publicly — no comment, label, or check shows reputation. Per-PR.
• GITTENSORY_REVIEW_UNIFIED_COMMENT — renders the public PR comment as one in-place unified comment instead of the legacy multi-panel comment. Per-PR. With the flag off, the legacy comment is byte-identical.
• GITTENSORY_REVIEW_ENRICHMENT — runs the review-enrichment analyzer registry (duplication, churn hotspots, blame links, approval integrity, undocumented exports, and more) and folds their findings into the review context. Per-PR.
• GITTENSORY_REVIEW_INLINE_COMMENTS — posts AI-review findings as inline diff-anchored PR review comments instead of (or alongside) the summary comment. Per-PR.
• GITTENSORY_REVIEW_PLANNER — enables @gittensory plan, an on-demand structured implementation plan posted to the PR thread. Per-PR.
• GITTENSORY_REVIEW_SCREENSHOTS — visual capture: renders and attaches before/after screenshots for PRs that change UI. Per-PR.
• GITTENSORY_REVIEW_OPS — observability, read-only. On the cron tick an anomaly scan over the gate-block ledger and calibration data emits a structured ops_anomaly log when something drifts, and a bearer-gated GET /v1/internal/ops/stats serves an outcome aggregate. Does not mutate config. Global.
• GITTENSORY_REVIEW_SELFTUNE — the self-improvement loop. On the cron tick it computes tuning recommendations from your own outcome data, shadow-soaks any strictly tightening recommendation, and auto-promotes it only after the soak passes. It can only ever tighten the gate — a loosening recommendation is never applied. Global, and safe to leave on.
• GITTENSORY_REVIEW_PARITY_AUDIT — parity readiness, shadow record-only. Records each finalized gate decision and serves a readiness report at GET /v1/internal/parity. Changes no review behavior. Global.
• GITTENSORY_REVIEW_CONTENT_LANE — routes content repos (curated lists, registries) through the dedicated content lane — duplicate detection, source-evidence reachability, security scanning, scope classification, registry grounding — instead of the code gate. Global.
• GITTENSORY_REVIEW_DRAFT — the public draft-submission flow (the /v1/drafts endpoints: contributor draft → GitHub OAuth → fork PR). With the flag off every draft endpoint 404s. Requires the DRAFT_TOKEN_ENCRYPTION_SECRET and GITHUB_OAUTH_CLIENT_SECRET secrets. Global.
• GITTENSORY_REVIEW_STATS_TOKEN — the bearer secret for the stats data endpoint. Not an on/off switch; it is the token value. When set, the stats route requires this bearer token.

Gate modes

Per-repo behavior is the effective settings: the database row for the repo, overlaid with the repo's .gittensory.yml. Most gate dimensions are tri-state:

• off — the dimension is not evaluated.
• advisory — the finding is surfaced in the comment or context but never blocks.
• block — the finding can become a hard Gittensory Orb Review Agent blocker. A block outcome fails the gate for any author identically — confirmed-Gittensor-contributor status doesn't change who can be blocked, only the mode chooses which deterministic checks are active. Confirmed status is carried through for on-chain scoring, a separate concern from the gate's own merge/close decision.

The master switch is gate.enabled (off / enabled). The per-dimension modes refine an already-enabled gate. The main dimensions:

• gate.pack — the policy pack: gittensor (default; registry-aware, tracks confirmed-Gittensor-contributor status for scoring) or oss-anti-slop (runs the deterministic rules against any author on any repo, with no confirmed-contributor tracking at all).
• gate.duplicates — duplicate / superseding-PR detection. Default block.
• gate.linkedIssue — what happens when a PR has no linked issue at all. Default advisory (surfaced in the review panel, never blocks — issues aren't always available). Set block, or turn on the dashboard "Require linked issue" toggle, to make a missing issue an explicit opt-in blocker (if the toggle is on but this is still off, it is auto-promoted to block). This is unrelated to closing a PR that links an ineligible issue (owner-assigned, wrong label, etc.) — that is a separate, deterministic rule, not this gate.
• gate.readiness.mode — the PR-quality / merge-readiness score gate. Default advisory. Pair it with gate.readiness.minScore (0–100; at or above this score the quality dimension passes; null uses the engine's default band).
• gate.slop.mode — the deterministic anti-slop signal. Default off (opt-in). advisory surfaces the slop score and warnings; block also hard-blocks at or above gate.slop.minScore (0–100; null uses 60, the "high" band). Set gate.slop.aiAdvisory: true to add a free advisory-only ai_slop_advisory finding — it never feeds the slop score or the gate.
• gate.mergeReadiness — composite merge-readiness gate. Default off, no min score.
• gate.manifestPolicy — when block, the manifest's declared policy (required linked issue and test expectations) becomes an enforceable blocker. Manual-review path holds use settings.hardGuardrailGlobs instead. Default off.
• gate.size — PR-size hold: flags an oversized diff. Default off.
• gate.lockfileIntegrity — flags lockfile-tamper risk (a lockfile changed without its matching manifest, or vice versa). Default off.
• gate.claMode — CLA / license-acknowledgment gate. Default off.
• gate.selfAuthoredLinkedIssue — whether a PR may link an issue opened by the same author. Default advisory.
• settings.moderationGateMode — whether the moderation-rules engine (contributor cap, blacklist, review-nag feeding a shared cross-repo violation tally) runs on this repo at all. inherit (default) defers to the instance-wide global_moderation_config.enabled; off/enabled force this repo regardless of the global default.
• gate.aiReview.mode — AI review. Default off. advisory posts AI review notes only; block lets a dual-model high-confidence consensus defect become a blocker.

Bring your own model (AI review)

The AI-review write-up can optionally use your own frontier model. By default the blocking decision runs on a pair of free built-in models and requires agreement; an operator can override this per repo with aiReviewCombine (single / consensus / synthesis) — in single mode, one reviewer's verdict is the decision. BYOK changes which model writes the advisory text, not this combine behavior.

• gate.aiReview.byok — when true and a provider key is configured, the advisory write-up uses the maintainer's frontier model. Default false.
• gate.aiReview.provider — anthropic, openai, or null (use the stored key's own provider). Must match the stored key's provider or BYOK is skipped and falls back to the built-in pair.
• gate.aiReview.model — model override for the BYOK write-up (for example claude-3-5-sonnet-latest); null uses the key record's model, else a conservative per-provider default.

Guardrails and scope

Top-level keys in .gittensory.yml declare the repo's focus and validation expectations. These feed deterministic findings such as manifest_missing_tests and — when gate.manifestPolicy: block — can become enforceable blockers. Manual path holds are configured only through settings.hardGuardrailGlobs.

• wantedPaths — globs for work areas you want; PRs touching these are preferred. Default [].
• preferredLabels — labels you prefer on incoming PRs; a missing one is surfaced. Default [].
• linkedIssuePolicy — required / preferred / optional. How strongly a linked issue is expected. Default optional.
• testExpectations — test paths expected to change with code; a manifest_missing_tests finding fires when absent. Default [].
• issueDiscoveryPolicy — encouraged / neutral / discouraged. Default neutral.
• maintainerNotes — private review context, never published to any public GitHub surface. Default [].
• publicNotes — notes explicitly opted into public output (public-safe filtered; unsafe lines are dropped). Default [].

Other repo settings

Anything you can toggle in the dashboard can also be set as code under settings: in .gittensory.yml. Common ones, all defaulting to the safe values shown:

• commentMode — comment audience: off / detected_contributors_only (default) / all_prs.
• publicAudienceMode — oss_maintainer (default) / gittensor_only.
• publicSignalLevel — minimal / standard (default).
• checkRunMode — check-run publishing: off (default) / enabled. Pair with checkRunDetailLevel (minimal (default) / standard / deep).
• publicSurface — off / comment_and_label (default) / comment_only / label_only.
• autoLabelEnabled (default true), gittensorLabel (default gittensor), and createMissingLabel (default true) — labeling.
• includeMaintainerAuthors (default false), requireLinkedIssue (default false), backfillEnabled (default true), privateTrustEnabled (default true), and badgeEnabled (README status badge, default false).
• agentPaused (per-repo kill-switch, default false) and agentDryRun (shadow mode, default false).
• autonomy (per-action-class level; default is observe, deny-by-default), autoMaintain ({ mergeMethod, requireApprovals }; default squash / 1), and commandAuthorization (role policy; built-in default).

Example .gittensory.yml

A worked manifest: focus and validation up top, a refined gate, BYOK AI review, and a few dashboard-equivalent overrides.

# Focus / validation
wantedPaths:
  - "src/**"
testExpectations:
  - "tests/**"
linkedIssuePolicy: preferred

# Gate policy (refines an enabled gate)
gate:
  enabled: true
  pack: gittensor
  duplicates: block
  linkedIssue: advisory
  readiness:
    mode: advisory
    minScore: 70
  slop:
    mode: block
    minScore: 60
    aiAdvisory: true
  mergeReadiness: advisory
  manifestPolicy: block
  aiReview:
    mode: advisory
    byok: true
    provider: anthropic
    model: claude-3-5-sonnet-latest

# Generic dashboard-equivalent overrides
settings:
  commentMode: detected_contributors_only
  checkRunMode: enabled
  checkRunDetailLevel: standard
  badgeEnabled: true
  # Optional path holds. Omitted or [] means no path guardrails.
  # hardGuardrailGlobs:
  #   - "src/selfhost/**"

For the privacy guarantees behind these surfaces, see Privacy & security. For the maintainer install and trust flow, see Install & trust.