Skip to content
Gittensory
Operating

Tuning your reviews

How to configure Gittensory CI and Gittensory review — gate modes, score thresholds, guardrails, and feature flags — through .gittensory.yml and your repo settings.

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.

Defaults are safe and conservative
Every feature flag ships OFF. A repo with no settings and no .gittensory.yml falls back to a quiet, non-blocking profile: the gate is off, AI review is off, slop scoring is off, comments go only to detected contributors, and no check-run is published. Turning anything on is always an explicit opt-in — you roll capabilities forward, and back, one flag and one repo at a time.

Precedence

Most specific wins:

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

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_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.
Rolling out a per-PR feature
A safe rollout is two flips: turn the capability flag true, then add the repo to GITTENSORY_REVIEW_REPOS. Because both must be true, you can leave a capability globally enabled while it stays dormant everywhere except the repos you have explicitly allowlisted — and you roll a single repo back by removing it from the list without disturbing the others.

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 Gate blocker. Blocking is always confirmed-contributor-gated: the mode chooses which deterministic checks are active, never who can be blocked.

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; confirmed-contributor-gated, registry-aware) or oss-anti-slop (runs the deterministic rules against any author on any repo).
  • gate.duplicates — duplicate / superseding-PR detection. Default block.
  • gate.linkedIssue — linked-issue gate. Default advisory. If the dashboard "Require linked issue" toggle is on but this is off, it is auto-promoted to block.
  • 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 (blocked paths, required linked issue, test expectations) becomes an enforceable blocker. Default off.
  • gate.firstTimeContributorGrace — when true, softens a would-be block to advisory for a genuine newcomer (0 merged PRs, fewer than 3 closed-unmerged PRs). Repeat offenders and authors with merge history are gated normally. Default false.
  • 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 (confirmed contributors only).

Bring your own model (AI review)

The AI-review write-up can optionally use your own frontier model. The consensus blocker always uses the free built-in model pair, so BYOK never changes who can be blocked.

  • 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.
The provider key itself never lives in .gittensory.yml. It is held only in the encrypted key store and unlocked by the TOKEN_ENCRYPTION_SECRET worker secret — absent that secret, BYOK is unavailable and AI review silently falls back to the free built-in model pair.

Guardrails and scope

Top-level keys in .gittensory.yml declare the repo's focus and guardrails. These feed the deterministic findings (such as manifest_blocked_path and manifest_missing_tests) and — when gate.manifestPolicy: block — can become enforceable blockers.

  • wantedPaths — globs for work areas you want; PRs touching these are preferred. Default [].
  • blockedPaths — globs off-limits to contributors. Touching one yields a manifest_blocked_path finding, enforceable when gate.manifestPolicy: block. 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 guardrails up top, a refined gate, BYOK AI review, and a few dashboard-equivalent overrides.

.gittensory.yml
# Focus / guardrails
wantedPaths:
  - "src/**"
blockedPaths:
  - "vendor/**"
  - ".github/workflows/**"
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
  firstTimeContributorGrace: true
  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
Roll forward one step at a time
Start conservative: enable the gate in advisory before block, watch the surfaced findings, and only then tighten. Combined with the tightening-only self-tune loop, this keeps the gate from ever blocking a contributor on a setting you have not validated.

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

← PreviousUpstream driftNext →Privacy & security