.maintainer.yml reference

Drop a .maintainer.yml at your repository root to configure the maintainer bot. The file is YAML; all fields are optional and default-safe — an empty file with only version: 1 is valid.

Schema autocomplete. Add # yaml-language-server: $schema=https://developerz.ai/schemas/maintainer.v1.json as the first line of the file to get IDE validation and autocomplete.

Minimal example

# yaml-language-server: $schema=https://developerz.ai/schemas/maintainer.v1.json
version: 1

Full example

# yaml-language-server: $schema=https://developerz.ai/schemas/maintainer.v1.json
version: 1

tone:
  voice: friendly
  language: en

triage:
  ask_for_repro: true
  required_fields: [steps, expected, actual, version]
  dedupe:
    enabled: true
    similarity_threshold: 0.85
  qualify_into: [bug, feature, dupe, question]

handoff:
  mode: webhook
  webhook_ref: my-claude-code-hook
  ask_reporter_first: true

pr:
  wait_for_other_bots: [coderabbit, copilot]
  required_checks: [ci]
  large_threshold_lines: 500
  auto_merge: true
  human_merge:
    branches: [main]
    paths: [db/migrations/**]

release:
  manager: release-please
  channels: [github-release]

escalate:
  always: [security, license, cla]
  ask_before_acting: [breaking, major, first-time-contributor, large]

digest:
  cadence: weekly
  day: monday
  time: "09:00"
  timezone: maintainer

limits:
  max_steps_per_session: 50
  max_comments_per_issue_per_day: 10

kb:
  repo_notes:
    - note: "Auth lives in packages/auth; ignore the legacy auth-old/ tree."
      by: "@maintainer"
  pages:
    - title: Architecture
      purpose: How the worker dispatches jobs.
  memory:
    stale_after_days: 90
    delete_unused_after_days: 40

review:
  profile: chill
  learnings: true
  anti_noise:
    severity_floor: minor
    max_comments: 30
  path_filters: ["!**/*.lock", "!dist/**"]

Root fields

tone

Controls the bot's voice and language in all comments.

triage

Governs how new issues are triaged: reproduction requests, deduplication, and label outcomes.

handoff

After qualification, the bot can hand off the issue to a coding agent. mode = webhook fires a signed POST to the configured webhook; mode = label applies a GitHub label your CI or coding agent can pick up; mode = none disables handoff.

When mode = webhook, webhook_ref is required. The webhook must be registered in the dashboard.

pr

Pull request review policy.

auto_merge is on by default. The bot merges once the machine gates pass — CI green, review verdict, and the repo's branch protections — never blindly. To keep a human in the loop, set auto_merge: false or list the sensitive branches/paths under human_merge. (Free-OSS-tier repos stay opt-in regardless.)

release

Release automation. The bot can cut releases after a PR merges based on conventional commit history.

escalate

Escalation rules. The bot always escalates security, license, and cla issues regardless of configuration — these cannot be disabled.

Built-in always categories (non-configurable): security, license, cla.

Built-in ask_before_acting categories: breaking, major, first-time-contributor, large.

digest

Weekly (or daily/monthly) email digest sent to the maintainer.

limits

Hard caps that prevent runaway agent behaviour.

coding

Knobs for the on-VM coding agent (BYOVM). Concurrency is a policy value, not a flag: it caps how many isolated git worktree checkouts run in parallel for the repo.

ci

Fences for the self-hosted CI runners the fleet boxes serve. The per-workflow opt-in is the label itself (runs-on: developerz-*); these two repo-wide booleans sit on top of it. Both are defaulted, so a repo that commits a policy but omits ci: still gets the safe fences.

mcp_servers

Array of external MCP servers the agent may call. Each entry:

Ref names (token_ref) resolve to secrets registered in the dashboard. The value is never stored in the policy file.

Example

mcp_servers:
  - name: linear
    url: https://mcp.linear.app/sse
    transport: sse
    token_ref: linear-api-key
    allowed_tools: [create_issue, search_issues]
    timeout_ms: 10000

kb

Repo-steered knowledge — a committed, reviewable way to correct or seed the agent's understanding of your repo. The bot reads it during triage alongside what it has learned on its own, so a short note here grounds answers without any code change.

kb.repo_notes

Short, attributed facts. Combined note length is capped at 10 000 characters.

kb.pages

An explicit table-of-contents that overrides the agent's auto-clustering. Up to 30 pages; titles must be unique and any parent must name another page.

kb.memory

Retention and consolidation settings for the bot's accumulated memories (learnings from past reviews, issues, and discussions). Distinct from repo_notes and pages (which are explicit, human-authored steering). Memory entries that grow stale or unused are pruned or merged automatically by the nightly gardener; these knobs tune that cleanup.

Consolidation. When consolidate: true, the gardener summarizes stale-but-still- referenced memories into KB pages via the account's BYOK model. When false, they are left as-is (or deleted if unused). Deletion. Set delete_unused_after_days to false to keep all memories forever; set a numeric value ≥7 to delete memories that have never been recalled (or recalled before the deletion cutoff).

Example

kb:
  repo_notes:
    - note: "Auth lives in packages/auth; ignore the legacy auth-old/ tree."
      by: "@maintainer"
    - note: "We never accept PRs that touch the vendored/ directory."
  pages:
    - title: Architecture
      purpose: How the worker dispatches jobs.
    - title: Dispatch
      purpose: Two-phase pull queue + per-entity lock.
      parent: Architecture
  memory:
    stale_after_days: 90
    delete_unused_after_days: 40
    consolidate: true

review

Native AI code review — a hosted, CodeRabbit-compatible reviewer running on your BYOK model, included in the seat. The native review: block is a superset of .coderabbit.yaml (adds anti-noise floor/cap and KB learning write-back); when the bot reads a .coderabbit.yaml it honors most fields but defers reviews.tools and reviews.finishing_touches (surfaced as warnings).

Precedence. If a repo has both a .coderabbit.yaml and a review: block, the review: block wins (.maintainer.yml > .coderabbit.yaml). The block is optional — omit it and the bot reads your existing .coderabbit.yaml (if any) or falls back to the built-in review defaults. Migrating off CodeRabbit is a no-op: keep the file, uninstall their app.

Bot etiquette. The reviewer always defers when another review bot (e.g. CodeRabbit, Copilot, Dependabot) is active on the repo — no bot-on-bot loops, no override. To hand review to the native reviewer, uninstall the other bot.

Anti-noise. Quiet by default (their #1 complaint): findings below anti_noise.severity_floor are dropped, volume is capped at max_comments, and repeats are deduped on re-push. Blocking findings (principle/gate violations) always bypass both the floor and the cap.

Example

review:
  profile: chill
  request_changes: true
  learnings: true # write review learnings back to kb
  anti_noise:
    severity_floor: minor
    max_comments: 30
  auto_review:
    base_branches: [main, release/*]
    ignore_title_keywords: [WIP, "DO NOT MERGE"]
  path_filters: ["!**/*.lock", "!dist/**"]
  path_instructions:
    - path: "packages/**/*.ts"
      instructions: "Enforce the repo principles in docs/idea/principles.md."

This page is generated from packages/policy/src/schema.ts. Run bun run scripts/policy-doc.ts to regenerate.