maintainer.yml reference

Commit .dz/maintainer/maintainer.yml to configure the maintainer bot. The root .maintainer.yml is the legacy path: still read until it is deprecated, and ignored when the .dz/ file exists. 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
  require_review: true
  human_merge:
    branches: [main]
    paths: [db/migrations/**]

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

escalate:
  always: [hostile_tone, direct_mention, paid_customer]
  ask_before_acting: [breaking_change, major_dep_bump, first_time_contributor, large_pr]

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: 10
  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 = fleet runs the work on your own enrolled boxes (BYOVM, never our hardware: the assigner claims the durable tasks row onto one of your boxes; no external webhook fires); mode = none disables handoff.

When mode = webhook, webhook_ref is required and the webhook must be registered in the dashboard. mode = fleet does not require webhook_ref.

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.)

require_review is on by default too, and it is what makes "review verdict" above a real gate: a head with no approving external review and no verdict from the built-in reviewer is handed to a human instead of merged. If your repo ships machine-gated on CI alone, set require_review: false. Deliberately, rather than by omission.

release

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

escalate

Escalation rules: when the bot emails you immediately, and when it drafts an action and waits for your approval instead of taking it.

Always escalated, not configurable: security, license, cla. Listing them is harmless but redundant, they fire whether or not always names them.

Accepted in always: security, license, cla, hostile_tone, direct_mention, paid_customer.

Accepted in ask_before_acting: breaking_change, major_dep_bump, first_time_contributor, large_pr.

Both lists are closed. A category outside them is a validation error on the whole file, and writing either key replaces its default rather than extending it.

digest

Not configurable, and there are no digest: keys. The digest is one message per account per week: every repo the account installs the bot on is summarised in the same message, sent weekly, Mondays at 09:00 UTC. It goes to each member whose own weekly_summary setting is on, or once to the account's verified digest.weekly route when one is set.

cadence, day, time and timezone used to be published here and were read by nothing; they were removed rather than left as decoration. A maintainer.yml that still carries the block is still valid; the keys are ignored, not rejected.

Switch the digest off per person with the weekly_summary preference, and drop the account-wide route under Email routes in the dashboard (digest.weekly). The unsubscribe link in the email footer is the per-recipient one-click.

coding

Knobs for the on-VM coding agent (BYOVM): which model tier each class of work gets, and how long this repo's own check may run after each edit batch.

bin/check and bin/clean

Two scripts are read by CONVENTION rather than configured here. Committing the script is the whole opt-in; neither has a key in this file.

bin/check is this repo's own gate, the one coding.check_timeout_ms above bounds. bin/clean is its cleanup sibling: an executable bin/clean in the checkout, run by the box that holds it. It is for the reclaim only your repo knows about, a cargo clean, a named compose volume, a generated asset tree. Our own sweep cannot guess those, so the repo says.

#!/usr/bin/env bash
# bin/clean - what only this repo knows how to reclaim. Must be executable.
set -euo pipefail
cargo clean
docker volume rm -f myapp_pgdata || true

ci

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

Two independent halves: enabled decides whether your CI jobs run on our boxes, self_fix decides whether the bot pushes a commit at a check that went red. Neither turns off observation, the merge gate always waits for green, whoever ran the job, so the bot never merges a red pull request.

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

integrations

Per-integration use grants, the config-as-code half of the credential gateway. Connecting an integration in the dashboard stores the credential; your yml must ALSO opt in here before the agent gets the gateway tool. The agent uses the connection through a platform-mediated tool, the credential is resolved server-side per call and never enters the model's context.

Example

integrations:
  slack: true # agent may post via the connected Slack workspace

tool_services

Per-repo config for the tool services the agent reaches as MCP servers. Config, never a credential: connect the service once in the dashboard and its key reaches the box as process env only, which the generated .mcp.json's ${VAR} references resolve against. Nothing here is secret, so the file stays safe to commit.

Keyed by service slug, an unknown slug is a validation error, not silently ignored. Only a service with its own config FILE takes a key here (ui-debugger's browser targets); one configured entirely by its env block needs nothing in your repo. The body is passed through verbatim to that service's own config file (.dz/ui-debugger/ui-debugger-mcp.json), so it is the tool's schema, not ours.

Setup mode writes the file establish-or-verify, never clobber: your existing file survives byte-identical, and a .example companion always ships so you can see the shape. Declare nothing and no live file is written, a guessed dev-server URL that 404s teaches the agent your app is broken.

Example

tool_services:
  ui-debugger:
    workspace: ./tmp/ui-debugger-mcp
    targets:
      dashboard:
        adapter: browser
        headless: true
        url: http://localhost:5173

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).

kb.background

Consent + cost caps for the BYOK-billed background KB work, the one-time import that seeds your wiki when the bot is first installed, and the nightly gardener consolidation. Both spend your own BYOK tokens, so this block governs whether they run at all and how large a wiki they may grow. Leave enabled unset to take the plan default (on for paid plans, off for the free OSS tier); set it explicitly to override.

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

schedules

Scheduled checkups: at each listed UTC hour on each listed day, a scout surveys this repo (plus any repos) from the brief you commit, and files what it finds as asks that triage sorts like any other report. It runs on your own boxes and your own key. Absent means nothing is scheduled. Days and hours, never a cron string: a cron typo fires every minute. Up to 10 entries; no field has a default, and a cron: key is refused.

Example

schedules:
  - name: nightly-checkup
    days: [mon, tue, wed, thu, fri]
    hours_utc: [2]
    brief_file: .dz/schedules/checkup.md
    repos: [acme/infrastructure]

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. To hand review to the native reviewer, uninstall the other bot, or set review.force: true to review in parallel while migrating off CodeRabbit.

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: 10
  auto_review:
    base_branches: ["release/.*"] # the default branch is always reviewed
    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."
  tolerated_check_failures: ["coderabbit:rate limit", "quota exceeded"]

This page is generated from the .maintainer.yml schema the parser validates against. Run bun run policy:doc to regenerate.