For Maintainers#

What Maintainers Get#

Gittensory helps maintainers review Gittensor-driven PRs with less noise. Instead of wading through a flood of contributions with no context on who the contributor is or whether the PR is ready for review, maintainers see structured intelligence pre-surfaced on each PR from a confirmed miner .

The system provides confirmed-miner context without check noise: one sticky public-safe comment and a configured label on demand, plus access to private reviewability packets through the API . Gittensory does not edit code, open PRs, close, merge, or label without an explicit user or maintainer-triggered flow. It is deterministic and auditable, not an autonomous PR bot .

Three Pillars for Maintainers#

1. PR Intelligence — Automatic sticky comment on PR threads for confirmed Gittensor miners with contributor context, hygiene signals, and duplicate/WIP risk .

2. Maintainer Commands — Invoke @gittensory@... commands on any PR to get on-demand intelligence .

3. Control Panel — Private reviewability packets, reviewability queue, installation health, and settings preview at /app/maintainer .

Quiet by Default#

The GitHub App is quiet by default: no automatic public output until configured . Once installed, there are no public check runs, no comments, no labels — you control what gets published and when. Every output surface is opt-in.

Why This Matters#

Open source maintainers often face a high volume of PRs with varying quality and readiness. Gittensor-driven contributions compound this challenge by introducing mining incentives that can lead to premature submissions, duplicate work, and incomplete context. Gittensory addresses this by surfacing structured intelligence at the PR level:

Contributor identity: Know which PRs come from official Gittensor miners versus outside contributors.
Review readiness: See hygiene signals, duplicate risk, and validation status before investing time in review.
Private context: Access detailed reviewability scoring and advisory findings through the control panel without polluting the public PR thread.
On-demand intelligence: Invoke @gittensory@... commands to get specific answers about any PR, from preflight checks to duplicate analysis.

The system respects your workflow. It does not force check runs, comments, or labels on you. It waits until you explicitly enable each output channel . This quiet-by-default posture ensures Gittensory fits into your existing review process without adding noise.

GitHub App Integration#

The Gittensory GitHub App is the installation point for all maintainer-facing features. It connects your repository to Gittensory's signals engine, enables PR intelligence comments, and powers the @gittensory command interface.

Installation#

Navigate to the Gittensory GitHub App listing.
Select the repositories to grant access.
Approve the requested permissions:
- Metadata: read
- Pull requests: read
- Issues: write
Optional permission: Checks: write — only required when check runs are enabled in repo settings

The app subscribes to four required webhook events: issues, issue_comment, pull_request, and repository .

Post-Installation Behavior#

After installation, Gittensory is quiet by default. No public checks, no comments, no labels are created automatically . The app listens to webhook events but does not produce any public output until explicitly configured.

Webhook events are queued for asynchronous processing . Each event is verified using an x-hub-signature-256 HMAC signature before processing .

Installation Health#

Installation health is available in the control panel at /app/maintainer . The system shows per-installation status: healthy, needs_attention, or broken .

Health checks verify:

Required permissions are granted
Required webhook events are subscribed
Installation metadata is current

When permissions or events are missing, the system shows remediation steps :

Update the GitHub App permissions and subscribed events.
Approve the changed permissions or reinstall the app on the target account.
Run refresh-installation-health after GitHub sends the updated installation payload.
Recheck /v1/readiness and the installation health endpoint.

Settings Preview#

The settings preview endpoint allows maintainers to dry-run what Gittensory would do for a sample PR without mutating GitHub :

POST /v1/repos/:owner/:repo/settings-preview

This endpoint returns:

Current repo settings
Installation health status
Missing permissions or events
Remediation guidance
Dry-run decision (skip, comment, label, or check run)
Preview label and check-run state
Sanitized public comment preview

Repository Configuration Options#

Settings are stored in the repositorySettings table and control how Gittensory behaves per repository :

Setting	Type	Default	Description
`commentMode`	`"off"`	`"detected_contributors_only"`	`"all_prs"`
`publicSignalLevel`	`"minimal"`	`"standard"`	`"standard"`
`checkRunMode`	`"off"`	`"enabled"`	`"off"`
`checkRunDetailLevel`	`"minimal"`	`"standard"`	`"deep"`
`autoLabelEnabled`	boolean	`true`	Automatically apply the configured label
`gittensorLabel`	string	`"gittensor"`	Label name to apply to PRs
`createMissingLabel`	boolean	`true`	Auto-create the label if it doesn't exist
`publicSurface`	`"off"`	`"comment_and_label"`	`"comment_only"`
`includeMaintainerAuthors`	boolean	`false`	Whether maintainer-authored PRs receive public output
`requireLinkedIssue`	boolean	`false`	Flag PRs without linked issues
`backfillEnabled`	boolean	`true`	Enable repository data backfill
`privateTrustEnabled`	boolean	`true`	Enable private trust signals

The default label is "gittensor" with description "Gittensor contributor context" .

Maintainer Focus Manifest#

Maintainers can create a .gittensory.json file (or .github/gittensory.json) in their repository to declare wanted paths, blocked paths, preferred labels, linked-issue policy, test expectations, issue-discovery policy, and maintainer notes. This focus manifest allows maintainers to signal their preferences to contributors before they open a PR.

Supported Fields#

wantedPaths (string array) — Path patterns for changes the maintainer wants to see. Supports exact paths, directory prefixes (e.g., src/), and wildcards (e.g., docs/**).
blockedPaths (string array) — Path patterns for areas the maintainer wants contributors to avoid. Matched paths trigger critical severity findings in preflight checks.
preferredLabels (string array) — Labels the maintainer prefers on PRs for triage alignment.
linkedIssuePolicy (string: "required", "preferred", or "optional") — Whether PRs must link to a tracked issue.
testExpectations (string array) — Free-form guidance on what test evidence the maintainer expects (e.g., "Run npm test locally before opening a PR").
issueDiscoveryPolicy (string: "encouraged", "neutral", or "discouraged") — Whether the maintainer welcomes new issue-discovery reports or prefers direct fixes.
maintainerNotes (string array) — Private review context for maintainers. Can be defined in the manifest configuration file to document internal review context, but is explicitly omitted from guidance objects returned to contributors and is never persisted in snapshots. This field was removed from the FocusManifestGuidance response schema for security reasons to prevent leaking private maintainer context to contributors, since guidance responses are contributor-facing.
publicNotes (string array) — Public guidance for contributors; shown in packet "Next Steps" and decision-pack recommendations after sanitization.

Example#

{
  "wantedPaths": ["src/", "test/"],
  "blockedPaths": ["config/secrets.yaml", "internal/**"],
  "preferredLabels": ["bug", "enhancement"],
  "linkedIssuePolicy": "required",
  "testExpectations": ["Run `npm test` locally", "Include test coverage for new features"],
  "issueDiscoveryPolicy": "encouraged",
  "publicNotes": ["Small, focused PRs are preferred", "Link discussion in issue thread"]
}

Parsing and Defaults#

The manifest uses tolerant parsing with safe defaults. Malformed config degrades gracefully with warnings instead of crashing analysis. Missing or invalid fields fall back to deterministic defaults:

Missing manifest or empty config → present: false
Invalid JSON → warning logged, empty manifest returned
Invalid field type → field ignored, warning logged
Unrecognized policy value → falls back to safe default

All public notes are sanitized to remove forbidden terms (wallet, hotkey, reward, payout, etc.) before appearing in packets or decision-pack guidance.

How It Works#

When a contributor prepares a PR packet or runs a local branch analysis, Gittensory:

Loads the manifest from the repo file (.gittensory.json or .github/gittensory.json) or a cached snapshot.
Matches the contributor's changed paths against wantedPaths and blockedPaths patterns.
Checks labels against preferredLabels.
Evaluates linked issues, test evidence, and validation results against manifest policies.
Generates findings with severity levels (info, warning, critical) and actionable guidance.
Adds a "Maintainer Focus" section to the PR packet (when the manifest is present) with public-safe next steps.
Merges manifest-driven recommendations into the decision pack's per-repo guidance.

Blocked paths trigger critical severity findings that surface as branch-quality blockers, preventing contributors from opening PRs in maintainer-off-limits areas without explicit confirmation.

PR Intelligence#

Gittensory surfaces structured, public-safe contribution context directly on GitHub PR threads for confirmed Gittensor miners. This intelligence is deterministic, metadata-only, and deliberately low-noise: maintainers receive one sticky comment with a configured label by default, with private reviewability scoring available separately via the API and control panel.

Sticky Comment Mechanism#

PR intelligence is delivered through a single, sticky comment that updates in place rather than creating duplicates. The comment uses an HTML marker  to identify itself for future updates . When a PR receives new activity, Gittensory refreshes the comment body in place rather than posting a new comment, keeping maintainer notification noise minimal.

The comment is only posted for contributors confirmed as official Gittensor miners via the Gittensor API . Non-miners, bots, and maintainers (unless includeMaintainerAuthors is enabled) receive no public output.

Comment Structure#

The sticky comment follows a consistent five-section structure with the header "## Gittensory contribution context" . An advisory notice at the top clarifies that the content is generated from public GitHub metadata and the local Gittensory cache and does not constitute an endorsement .

1. Contributor Context#

This section provides maintainers with the contributor's identity and Gittensor activity profile:

Author login — GitHub username
Confirmed Gittensor miner status — "yes" if confirmed via the official Gittensor API, "not confirmed" otherwise
Role context — Classification as outside contributor, collaborator, maintainer, or owner, plus whether this is maintainer-lane work
Gittensory signal — Detection reason ("Official Gittensor API confirms this GitHub user" for confirmed miners, or "No confirmed Gittensor miner activity detected" for unconfirmed authors)
Prior cached PRs/issues — Count of prior pull requests and issues from the contributor in registered repos
Public profile languages — Top programming languages from the contributor's public GitHub profile

2. PR Hygiene#

This section summarizes the PR's structural quality:

Linked issues — List of issue numbers the PR closes via keywords (e.g. #42, #57), "None detected" if the repo requires linked issues but none are present, or "Not required by this repo setting" if the repository has requireLinkedIssue disabled
Lane context — Summary of the repository's Gittensor participation lane (direct_pr, issue_discovery, split, inactive, or unknown) with guidance appropriate to the lane
Review burden — Classification as low, medium, or high based on changed file count and collision signals

3. Duplicate/WIP Risk#

This section alerts maintainers to potential duplicate or overlapping work:

Collision clusters found — Count of collision clusters that include this PR or its linked issues, computed from overlapping titles, shared linked issues, or term-overlap heuristics
Queue level — Repo-wide burden level (low, medium, high, critical) derived from open PR count, unlinked PRs, stale PRs, and collision signals

4. Maintainer Notes#

This section lists up to 5 public-safe advisory findings (or 2 if the repo's publicSignalLevel is set to "minimal"). Findings are filtered to exclude critical severity items and any text containing private scoring terms . If no public-safe findings are available, the section displays "No public-safe advisory findings were generated from cached metadata" .

Advisory findings include codes like:

missing_linked_issue — No linked issue detected when the repo requires one
possible_duplicate_work — Collision clusters suggest overlapping work
missing_test_evidence — Code changes without test file evidence
checks_need_attention — Failing or cancelled CI checks

5. Contributor Next Steps#

This section provides actionable guidance for the contributor, filtered to ensure no private scoring terms appear :

Link issues or explain no-issue PRs (if requireLinkedIssue is enabled and no issues are linked)
Check overlapping issues/PRs before review continues (if collision clusters are present)
Address specific findings from the maintainer notes (if actions are provided)
Maintainer-lane context notice (if the contributor is detected as a maintainer)

If no steps are generated, a default message appears: "Keep the PR focused and include validation evidence before maintainer review" .

Reviewability Scoring#

Gittensory computes a private reviewability score (0-100) for each PR, starting at 100 and deducting points based on noise sources :

Base calculation: 100 minus (14 × noise sources count)
Deductions:
- −12 per collision cluster
- −18 per failing check
- −18 for broad diffs (≥12 files or ≥800 total changes)
Bonuses:
- +12 for existing approvals

The score maps to five maintainer actions :

review_now (≥75): "Reviewing now is efficient because cached signals show linked context and manageable friction."
needs_author (45-74): Ask the author to address concrete missing context before deep review.
likely_duplicate: Check for overlapping work before reviewing.
close_or_redirect: Non-open or stale PRs that should be redirected.
watch: Lower-cost monitoring until signals improve.

This private reviewability scoring is available only through the API and control panel, not in public GitHub comments .

Contributor Context Depth#

Gittensory builds a multi-dimensional picture of contributor history for maintainer review, sourced from the official Gittensor API when available or from cached GitHub data :

Role context: Classification as outside contributor, collaborator, maintainer, or owner based on GitHub association and prior work patterns
Outcome context: Merged PR count, closed PR rate, and open PR count specific to the repository
Credibility signals: Derived from prior merged PRs, closed PR rate, and open PR pressure

For example, if a contributor has a 37% closed PR rate in the repo, that signals potential credibility risk .

Risk Signals and Flags#

Gittensory flags multiple categories of risk to help maintainers triage PRs efficiently :

Hygiene & Linkage:

Missing linked issue or no-issue rationale
Unlinked PRs (0 linked issues)
Duplicate/WIP collision clusters

Technical & Process:

Code changes without cached test files
Failing or cancelled checks
Broad diffs (≥12 files or ≥800 changes)

Contributor History:

High closed PR rate (≥35%) in the repo
Maintainer association (which requires separate maintainer-lane review)

Repo Queue:

Stale PRs (14+ days without update)
High collision clusters
Strained or blocked contributor intake health

These signals are derived deterministically from cached GitHub metadata—no AI or subjective judgment is involved.

Maintainer Noise Report (Repo-Wide)#

At the repository level, Gittensory aggregates queue pressure into a single "noise score" (0-100) with a corresponding level: low, medium, high, or critical . This report is available via the control panel and includes:

Count of unlinked PRs
Collision cluster count
Stale PRs (14+ days without update)
Broad-diff patterns
Contributor intake strain level

The noise report helps maintainers understand whether their repo is under queue pressure and should delay inviting additional Gittensor contribution flow .

Optional AI Layer#

Gittensory includes an optional AI rewrite layer that translates deterministic signal bundles into friendlier prose using Llama 3.1 . This layer is disabled by default (AI_SUMMARIES_ENABLED=false, AI_PUBLIC_COMMENTS_ENABLED=false).

When enabled, the AI layer:

Rewrites compact signal bundles into conversational text
Falls back to deterministic templates on any error, quota exceeded, or unsafe output
Never changes the facts—only restates them in friendlier language
Operates on metadata-only signal bundles that deliberately exclude PR titles, bodies, diffs, and source code

The deterministic facts remain authoritative. AI output is sanitized through the same public/private boundary enforcement used for all public comments .

Public/Private Data Boundary#

All public GitHub output routes through a sanitizer that strips forbidden terms including wallet, hotkey, coldkey, reward, scoreability, farming, and payout . Private scoring context—including exact reviewability scores, reward/risk projections, and detailed credibility breakdowns—remains accessible only via the API and control panel with session authentication .

The public sticky comment provides enough context for maintainers to triage effectively without exposing private contributor scoring data.

Maintainer Commands#

Maintainers can interact with Gittensory directly in GitHub PR and issue threads by mentioning @gittensory with a command. These commands provide public-safe intelligence about PRs, contributors, and repository fit without exposing private scoring internals.

How Commands Work#

Comment @gittensory <command> on any PR or issue thread in an installed repository . Commands are case-insensitive and parsed using the pattern /(?:^|\s)@gittensory(?:\s+([a-z-]+))?/i. If no command is specified or an unknown command is provided, the system defaults to the help command.

All commands were centralized and standardized in PR #190: feat(github-agent): complete command router v2.

Authorization#

Command access is role-based :

Maintainers (OWNER, MEMBER, or COLLABORATOR): Full access to all commands, no additional checks required
PR authors: Access granted only if they are confirmed official Gittensor miners
Bots: Silently skipped
Non-PR threads from non-maintainers: Silently skipped

Available Commands#

Commands are grouped into two categories: public commands (available to PR authors who are confirmed Gittensor miners and to maintainers) and maintainer-only commands (restricted to OWNER, MEMBER, or COLLABORATOR association).

Public Commands#

`@gittensory help`#

Shows the complete list of available commands with brief descriptions .

Example:

@gittensory help

`@gittensory preflight`#

Summarizes PR hygiene and validation readiness. Shows up to 3 relevant actions from preflight analysis, including linked context, branch freshness, and validation status .

Example:

@gittensory preflight

`@gittensory blockers`#

Lists public-safe readiness blockers that might prevent a PR from being ready for review. Shows up to 4 actions with blocker details. Useful when you need to understand exactly what is blocking a PR from moving forward .

Example:

@gittensory blockers

`@gittensory duplicate-check`#

Detects duplicate risks, work-in-progress collisions, and related overlap signals. This command helps you avoid spending review effort on potentially redundant work before diving into a detailed review .

Example:

@gittensory duplicate-check

`@gittensory miner-context`#

Confirms Gittensor miner status for the PR author. Shows the confirmed miner's GitHub username, total PR count in registered repos, and merged PR count .

Example:

@gittensory miner-context

Sample response:

GitHub user alice is confirmed by the official Gittensor API.
Registered-repo PRs observed by Gittensor: 47.
Merged registered-repo PRs observed by Gittensor: 23.

`@gittensory next-action`#

Suggests the next public-safe work step, cleanup action, or monitoring recommendation. Useful for guiding a contributor toward their next move or deciding what action to take next as a maintainer .

Example:

@gittensory next-action

`@gittensory reviewability`#

Summarizes maintainer-friendly PR readiness without exposing private review internals. Shows PR readiness status and validation details for up to 3 actions. This command was introduced in the command router v2 update .

Example:

@gittensory reviewability

`@gittensory repo-fit`#

Analyzes repository fit from cached public-safe signals. Shows the target repository and fit assessment for up to 4 actions. Introduced in command router v2 .

Example:

@gittensory repo-fit

`@gittensory packet`#

Prepares public-safe PR packet guidance for up to 3 actions. The packet includes a structured document with summary, linked context, branch freshness, GitHub status, overlap/WIP checks, changed paths, validation, and next steps. Introduced in command router v2 .

The response includes an explicit disclaimer: "Use this as public PR-thread guidance only; keep private scorer context in MCP or the control panel."

Example:

@gittensory packet

Maintainer-Only Commands#

Maintainer-only commands are restricted to users with OWNER, MEMBER, or COLLABORATOR association. These commands provide queue digest functionality from cached GitHub metadata and are designed to give maintainers queue-level intelligence without requiring agent runs.

All maintainer-only commands build digests from cached public GitHub metadata, cached check summaries, PR age, queue pressure, duplicate clusters, and cached confirmed-miner status. Output is public-safe and points to the authenticated maintainer dashboard for private details.

`@gittensory queue-summary`#

Posts a maintainer-only queue digest with overall statistics. Shows queue level (low, medium, high, critical), open issues, open PRs, review-now candidates, needs-author items, confirmed-miner PRs, duplicate clusters, unlinked PRs, stale PRs, and maintainer-authored PRs.

Example:

@gittensory queue-summary