Approvability

Disabled by default. Enable per repo in Settings → Repos → Approvability.

How It Works

When a PR is opened or updated, Macroscope evaluates up to three criteria before auto-approving. Ownership (via CODEOWNERS) is disabled by default; Eligibility and Correctness are always active. All active criteria must pass for auto-approval — if any fail, the PR can still be approved manually.

1. Eligibility

Is this PR a good candidate for auto-approval? Macroscope evaluates the changes, code ownership, git blame history, and the author’s role. If your repo has a CODEOWNERS file, Macroscope factors in the author’s relationship to changed files.

Typically eligible: docs, tests, code behind feature flags, simple bug fixes, copy changes.
Not eligible: large refactors, schema changes, security/auth/billing code, breaking changes.

2. Correctness

Did the PR pass Macroscope’s code review with zero issues flagged?

Minimum Blocking Severity

Minimum Blocking Severity is a per-repo setting that controls which severity of unresolved correctness comments blocks auto-approval. Outstanding correctness comments at or above the configured severity block approval; comments below the threshold do not. Choose from Low, Medium, High, or Critical — the default is Medium. Find it in Settings → Repos → Approvability (shown once Approvability is enabled). Only a GitHub Admin can change it.

Results appear as Macroscope - Approvability Check in the Checks tab and as a PR comment with detailed reasoning.

Custom Eligibility Rules

Add a .macroscope/approvability.md file to your repo to define rules on top of the defaults. Your custom rules are additive — they are combined with the built-in eligibility criteria, not a replacement.

Plain text rules

The simplest approach is a plain markdown file with your rules:

If a PR changes files in any of the following paths, DO NOT auto-approve:
- services/auth
- services/billing
- targets/auth

Front matter configuration

For more control, add YAML front matter to configure the approvability agent’s behavior:

---
tools:
  - github_api_read_only
  - modify_pr
conclusion: neutral
---

If a PR changes files in any of the following paths, DO NOT auto-approve:
- services/auth
- services/billing
- targets/auth

If the verdict is "needs human review" and the PR touches services/auth/,
request a review from @security-team.

Supported fields

Field	Default	Description
`tools`	`[]`	Additional tools for the approvability agent. The agent always has file browsing and git tools; this field adds more capabilities.
`conclusion`	`neutral`	Controls the check run result when a PR needs human review. `neutral` (default, recommended) means the check is informational — it never blocks merging. To gate merge on human approval, use GitHub’s required reviewers. `failure` makes the check hard-block merge via required status checks — see caveats before enabling.
`waitsFor`	Correctness, Check Run Agents & external review tools	Additional check run names that must complete before approvability runs. Even when unset, approvability automatically waits for the Correctness check, every Check Run Agent on the commit, and recognized third-party review tools (Cursor BugBot, CodeRabbit, Greptile) before deciding — this field adds prerequisites on top of those. Supports `["*"]` wildcard to wait for all check runs. See Waiting for Other Checks.
`waitsForTimeout`	`20`	How long to wait for prerequisites, in minutes (`1`–`60`). Only meaningful when `waitsFor` is set.

Available tools

Tools extend what the approvability agent can do beyond its defaults (file browsing and git tools):

github_api_read_only — search code and read GitHub metadata
modify_pr — request reviewers or post PR reviews
slack — post messages to Slack channels
launchdarkly — check feature flag status
web_tools — search the web
issue_tracking_tools — query linked Jira/Linear tickets

The modify_pr tool enables instructions like “request a review from @security-team when the verdict is needs human review.” Without it, the agent can only analyze and report — it can’t take actions on the PR.

Waiting for other checks

By default, approvability waits for the Correctness check, any Check Run Agents, and recognized third-party review tools (Cursor BugBot, CodeRabbit, Greptile) before making its decision, so their findings are considered in the verdict. Use waitsFor to also wait for additional CI steps — for example, linters, deployment checks, or other external tools not covered by the built-in list — whose results should influence the approval verdict. Wait for specific checks:

---
waitsFor:
  - "CI / lint"
  - "Macroscope - Security Review"
conclusion: neutral
---

If CI lint or the security review flagged issues, DO NOT auto-approve.

Wait for all checks (wildcard mode):

---
waitsFor:
  - "*"
---

Consider findings from ALL CI steps when deciding whether to auto-approve.

Wildcard mode waits for every check run on the commit except Macroscope - Approvability Check itself. This is useful when you have multiple Check Run Agents posting review comments and want approvability to consider all of their findings. Custom timeout: The default wait is 20 minutes. Set waitsForTimeout to change it (1–60 minutes):

---
waitsFor:
  - "deploy-to-staging"
waitsForTimeout: 45
---

Behavior summary:

Scenario	What happens
Prerequisites complete	Approvability proceeds with its eligibility assessment, considering review comments posted by the waited-for checks.
Prerequisite not found after 60 seconds	The prerequisite is treated as timed out. Check that the name in `waitsFor` matches the check run name exactly as it appears on GitHub.
Prerequisite does not complete within timeout	Approvability proceeds without waiting further. Increase `waitsForTimeout` if the step is slow.
Circular dependency	Detected at parse time. For example, if a CRA has `waitsFor: ["Macroscope - Approvability Check"]` and approvability has `waitsFor: ["*"]`, the cycle is detected and the affected CRA skips with a descriptive error.

Approvability always waits for the Correctness check and recognized third-party review tools (Cursor BugBot, CodeRabbit, Greptile) regardless of waitsFor — this field controls additional prerequisites beyond those built-in waits. Named mode supports up to 10 entries.

Using approvability as a required status check

Most teams should leave conclusion at the default (neutral) and use GitHub’s required reviewers to gate merge on human approval. The approvability check surfaces the verdict; the reviewer requirement does the blocking. This is the simplest and most predictable setup.

If you want the approvability check itself to hard-block merge when the verdict is “needs human review,” set conclusion: failure in front matter and add Macroscope - Approvability Check as a required status check in your branch protection rules. Be aware of how GitHub handles this combination:

The check concludes as failure when the verdict is “needs human review,” which blocks merge.
A PR review approval alone does not clear a failing required status check. GitHub treats approvals and status checks as independent gates.
The check stays in failure until a new commit is pushed or the check is manually re-run, at which point the approvability agent re-evaluates the PR.

In practice, this means a human can approve the PR but still cannot merge until the check is re-triggered.

The legacy path macroscope_approvability.md at the repo root is still supported for backward compatibility, but .macroscope/approvability.md is the recommended location. Front matter is only supported in the .macroscope/approvability.md path — the legacy path treats the entire file as plain text rules.

Setup

Enable Approvability in Settings → Repos.
(Recommended) Add a CODEOWNERS file to your repo.
(Optional) Add a .macroscope/approvability.md file with custom eligibility rules and front matter configuration.

Macroscope cannot approve its own PRs.

Getting Started

Agent

Code Review

Status

Support

How It Works

1. Eligibility

2. Correctness

Minimum Blocking Severity

Custom Eligibility Rules

Plain text rules

Front matter configuration

Supported fields

Available tools

Waiting for other checks

Using approvability as a required status check

Setup

​How It Works

​1. Eligibility

​2. Correctness

​Minimum Blocking Severity

​Custom Eligibility Rules

​Plain text rules

​Front matter configuration

​Supported fields

​Available tools

​Waiting for other checks

​Using approvability as a required status check

​Setup

How It Works

1. Eligibility

2. Correctness

Minimum Blocking Severity

Custom Eligibility Rules

Plain text rules

Front matter configuration

Supported fields

Available tools

Waiting for other checks

Using approvability as a required status check

Setup