Pullmaster Documentation

Getting Started

Installation

1. Install the Pullmaster GitHub App on your organization or personal account.
2. Select which repositories Pullmaster should have access to.
3. That's it — Pullmaster learns from your repository history automatically. No configuration is required to start.

Usage

Mention @pullmasterai in any pull request comment with one of the supported commands:

Commands are case-insensitive and only work on pull request comments (not regular issues). They run only when you post a new comment — editing an existing comment will not trigger them.

A plain @pullmasterai mention without a command is treated as feedback, not a reviewer suggestion.

What Pullmaster Considers

Pullmaster evaluates every eligible reviewer using multiple signals, including:

• File familiarity — Who has worked on the changed files recently
• Code ownership — Designated maintainers defined in your PULLMASTER file
• Author-reviewer affinity — Who has successfully reviewed this author's work before
• Semantic expertise — Matching based on how your code actually fits together
• Review quality — Depth and thoroughness of past reviews
• Availability — Current workload and past review responsiveness

Reviewers with several pending change-request reviews are de-prioritized so overloaded teammates are not assigned more work, unless they are clearly the right person for the PR.

Pullmaster automatically adapts its recommendations based on the risk level of each PR. Critical changes to core files surface your most experienced reviewers, while routine updates are distributed across the team to reduce bottlenecks.

Code areas & ownership health

Pullmaster groups your repository's meaningful source files into named code areas (typically 4–15 per repo) based on file history, pull request activity, and file structure. Each area shows who owns the knowledge and where concentration risk lives.

Ownership health

Each repository gets an Ownership health score from 0–100 (100 = healthy knowledge spread; lower = more concentration risk). Summary metrics include:

• Critical (bf 0) — Areas with no meaningful owner
• Bus factor 1 — Areas with a single meaningful owner
• Unowned — Areas with no contributors at all
• Healthy (bf ≥ 2) — Percentage of areas with adequate backup coverage
• Most concentrated — The collaborator who appears most often as a sole or dominant owner

Per-area details

The code areas table shows Primary owner, Backup owners, Bus factor, Concentration, Files, and an At risk or OK badge for each area. Expand an area to see Why this is risky, backup candidates, recommended actions, contributor breakdown, and the full file list. You can rename areas; custom names persist across rebuilds.

When code areas refresh

• When you install Pullmaster or add a repository
• After pushes to the default branch (at most once per day)
• When you open the Code areas page and data is older than ~30 days
• Anytime via the Rebuild code areas button

What's excluded

Analysis excludes vendored, generated, and documentation files; test files; config and schema boilerplate; and anything matched by .gitignore, .dockerignore, or .npmignore.

Sign in to the Pullmaster dashboard, then open Code areas → for any repository.

Generated CODEOWNERS preview

Pullmaster can generate a suggested CODEOWNERS file from your code areas and contributor familiarity. The preview starts with # Generated by Pullmaster and assigns up to three owners per area, with backup suggestions for risky areas and optional catch-all rules.

This is a preview only — Pullmaster does not write it to your repository. Copy it manually if you want to use it. This is separate from your PULLMASTER file, which Pullmaster reads for path ownership during reviewer matching.

Find it on the installations page via Preview CODEOWNERS for any repository.

PULLMASTER File

The PULLMASTER file is an optional configuration file that lets you define path ownership rules that boost reviewers who own the changed files. It uses the same format as GitHub's CODEOWNERS file.

Why PULLMASTER instead of CODEOWNERS?

GitHub automatically requests reviewers listed in a CODEOWNERS file — there's no way to disable this behavior other than deleting or renaming the file. By renaming it to PULLMASTER, you stop GitHub's automatic reviewer requests while still giving Pullmaster the ownership data it needs for smarter recommendations.

File Locations

Pullmaster looks for the file in these locations (first match wins):

1. PULLMASTER (repository root)
2. .github/PULLMASTER
3. docs/PULLMASTER

The file is read from the repository's default branch.

File Format

The PULLMASTER file uses the same syntax as GitHub's CODEOWNERS file. See GitHub's documentation on CODEOWNERS syntax for the full format reference. Both individual users and teams are supported.

Migrating from CODEOWNERS

If you already have a CODEOWNERS file and want Pullmaster to handle reviewer selection instead of GitHub:

1. Rename your CODEOWNERS file to PULLMASTER (keep it in the same directory).
2. No other changes needed — the file format is identical.

Reviewer Escalation

When a reviewer doesn't respond to a pull request within a configurable timeout, Pullmaster can automatically request a review from the next best candidate. This prevents PRs from going stale when a reviewer is unavailable.

How It Works

1. If a reviewer assignment has been pending longer than your configured timeout and there is no reviewer activity on the PR, Pullmaster selects a new reviewer using its scoring pipeline and requests their review on GitHub.
2. This repeats up to your configured maximum number of escalations per PR.

Pullmaster skips escalation if the PR has any review, or any human comment that is not a @pullmasterai command (such as suggest or assign).

Configuration

Reviewer escalation is a per-user preference. Configure it from the settings section on your installations page:

• Escalation timeout — How many hours to wait before escalating (leave blank to disable escalation)
• Max escalations — Maximum number of additional reviewers to add per PR (default: 2)

MCP repo intelligence

Connect Pullmaster's read-only repo intelligence to Cursor, Claude Desktop, or any MCP client that supports OAuth 2.1. No separate install is required beyond the GitHub App.

Connection

• MCP endpoint — https://app.pullmaster.ai/mcp
• Protected resource metadata — https://app.pullmaster.ai/.well-known/oauth-protected-resource

Authentication uses OAuth 2.1 with PKCE and the mcp scope. Sign in to Pullmaster with GitHub before authorizing your MCP client.

Setup

1. Install the Pullmaster GitHub App and sign in at app.pullmaster.ai.
2. On the installations page, find the Connect MCP client card.
3. Add the MCP endpoint URL to your client (Cursor, Claude Desktop, or another OAuth-aware MCP client).
4. Complete the OAuth authorization prompt in your browser.

Available tools

All tools are read-only:

How Pullmaster Learns

Pullmaster builds reviewer profiles automatically from your repository activity — push events, pull request reviews, and code changes. There is no manual training step.

When you first install the GitHub App, Pullmaster runs a one-time backfill of roughly the last 180 days of history: commits, pull requests, reviews, file touches, ownership rules, code areas, and embeddings. After that, Pullmaster keeps learning from new webhooks as your team works.

Repositories added to an existing installation later do not receive a full historical backfill; they learn incrementally from new activity going forward.