Skip to main content
Approvability evaluates whether a PR can be approved without human review. Approvability evaluates eligibility, correctness, which are off by default. All active conditions must pass for automatic approval. Macroscope cannot approve its own PRs. Control when Approvability runs under Settings → Repos → Features. Choose a run mode, then use Preview Mode to evaluate PRs without submitting approvals. Price: 30 Agent credits (= $0.30) when the eligibility agent runs; deterministic decisions are free. Learn more: Agent pricing.

Run mode

Run mode controls when Approvability runs. See run-mode choices in Settings. A manual run can submit an approval when Preview Mode is off. Changing run mode does not change Preview Mode. Rerunning a check from GitHub’s Checks tab does not count as a manual trigger for Manual invocation only.

Approvability Mode

Approvability Mode controls how cautiously the eligibility agent assesses a PR:
  • Permissive (default): leans on the pull request’s verifiable evidence (Correctness, Check Run Agents, CI, review comments, CODEOWNERS, etc.). It treats human review time as costly, reserving it for material risk that needs human judgment.
  • Strict: takes a more cautious approach, asking for human review when meaningful risk or material uncertainty remains after considering the change’s safeguards. Passing CI and verified correctness alone are not enough to justify approval by Macroscope.
Your custom eligibility rules strongly apply in both modes. Approvability Mode does not change when Approvability runs or whether Preview Mode withholds approvals. Workspace admins can change it under Settings → Repos → Approvability → Approvability Mode. A mode key in .macroscope/approvability.md front matter overrides this setting for the repository. See Overriding Approvability Mode.

Preview Mode

Turn on Preview Mode to see which PRs Macroscope would approve without submitting approvals. It is off by default and is available in Approvability settings and during onboarding. To set Preview Mode in the repository instead, add preview: true or preview: false to the front matter of .macroscope/approvability.md. An explicit value overrides the setting in either direction; omit the key to use the setting. Setting the run mode to Never run still stops Approvability regardless of the file. Eligibility rules, correctness checks, and your custom policy still apply. When all conditions pass, the verdict is Would Approve and the check concludes neutral, identifying Preview Mode as the reason. An ineligible PR can still receive Needs Human Approval; the comment explains any blockers. Turning Preview Mode off does not retroactively approve a previewed PR. Request a new run with @macroscope-app to evaluate it for approval. See Correctness for how resolving review threads updates an existing verdict.

Eligibility

The Eligibility agent decides if this PR is 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.

Verdicts

A verdict and a GitHub check conclusion are different. For example, a protected-path Skipped verdict concludes neutral. See blocking behavior.

Custom eligibility rules

Add .macroscope/approvability.md. The Markdown body adds to the built-in criteria, which favor small, low-risk changes and hold refactors, schema changes, security-sensitive code, and breaking changes for human review.
The file is read from the latest PR commit. A PR that changes the approval file itself is always held for a human, including the PR that first adds it.

Supported fields

Invalid values are reported as warnings in the Approvability check run details. The following check-run-agent fields are ignored here, with a warning: title, model, input, reasoning, effort, include, exclude, maxBudgetPerRun, and maxBudgetPerPR. requires is not supported here and is ignored with a warning. Use waitsFor and state how failed checks should affect eligibility in your instructions. Additional tools include github_api_read_only, modify_pr, slack, launchdarkly, web_tools, issue_tracking_tools, and mcp. For example, modify_pr allows instructions to request a security reviewer when a PR is not approved. Connected tools require their integration. mcp uses your workspace’s MCP connectors; see MCP in automated agents for which connectors are available. The legacy root file macroscope_approvability.md still works as plain-text rules; it does not support front matter.

Overriding Approvability Mode

Set mode to strict or permissive to override the repository’s Approvability Mode setting:
  • mode overrides the repository setting in either direction: a file can set strict on a permissive repository or permissive on a strict one.
  • Omit mode to use the repository setting.
  • Values are case-sensitive. An invalid value, such as Strict, is ignored: the repository setting applies, and a warning appears in the Approvability check run details.
Like any change to .macroscope/approvability.md, a PR that adds or edits mode is always held for human review.

Correctness

By default, unresolved correctness comments at or above Minimum Blocking Severity block approval. Comments remain outstanding until their thread is resolved or the comment is deleted. Findings without recorded severity count as Medium. When the final blocking thread is resolved, Macroscope approves if Preview Mode is off, the run mode permits approval, and no other requirements block it. With Preview Mode on, it updates the check but keeps the Would Approve verdict without approving. No new commit is needed. Reopening a blocking thread withdraws any Macroscope approval. Rerun Approvability once if an older PR does not update.

Minimum blocking severity

Workspace admins can choose Low, Medium (default), High, Critical, or Off in repository Approvability settings. Workspace defaults apply to new repositories; batch-edit existing ones. Off removes the deterministic correctness gate, including missing or unreported reviews. The eligibility agent still sees findings and may recommend human review. With a threshold set, a correctness comment below it does not by itself require human review. This is separate from Minimum Severity to Comment, which controls which findings are posted. Withheld findings remain available as risk context. To exclude correctness from the eligibility judgment too, say so explicitly in the rules:
General instructions about external reviewers do not disable the correctness gate.

Missing correctness review

Raise the relevant limit or request a manual correctness review. Manual requests bypass correctness run-count and per-review/per-PR spend caps, but not the workspace balance or monthly limit. Off or explicit rules excluding correctness remove the missing-review gate too. If a limit stops Approvability itself, there is no verdict comment: the check concludes skipped. Workspace balance/monthly limits and the correctness per-PR cost cap can stop it. The Check Run Agents per-PR limit cannot. See spend controls.

Limiting approval scope

Use onlyApprove in .macroscope/approvability.md front matter to limit which PRs Approvability evaluates:
Every changed path must match at least one pattern; renames must match at both old and new paths. Any path outside the scope skips Approvability without running or charging for the eligibility agent. In-scope PRs continue through normal evaluation, including neverApprove, alwaysApprove, and all other approval gates. Omit onlyApprove to preserve existing behavior. Empty lists, blank entries, and invalid patterns fail validation rather than removing the restriction.

Protecting review configuration

Approval-file protection

Any addition, edit, rename, or deletion of .macroscope/approvability.md or the legacy approval file holds the PR without running the eligibility agent. No setting or instruction can remove this protection.

neverApprove: additional protected paths

Any changed file matching neverApprove holds the whole PR. Use it for workflows, review configuration, or sensitive code. Only the approval file is protected automatically, so list other Macroscope configuration yourself:
The verdict is Skipped and the check concludes neutral, even with conclusion: failure. Renames check both old and new paths; deletions count.

Path patterns

Patterns are globs matched against paths relative to the repository root, such as docs/README.md. alwaysApprove and onlyApprove match the same way.
  • A pattern without / matches at any depth: AGENTS.md is the same as **/AGENTS.md.
  • A pattern with / is anchored to the repository root: docs/** covers only the top-level docs folder.
  • * matches within one path segment; ** spans directories.
  • {a,b} matches either alternative; [Aa] matches one listed character.
  • Matching is case-sensitive.
These patterns are accepted but match nothing, so they protect nothing:
  • /AGENTS.md or ./AGENTS.md: paths have no leading / or ./. Use AGENTS.md.
  • docs/: a trailing slash matches no file. Use docs/**.
  • docs: matches only a file named docs, not a folder’s contents. Use docs/**, or **/docs/** for any depth.
Only unparseable patterns, such as src/[a-.go, are dropped with a warning in the check output. To confirm a pattern, open a PR that touches a matching path and check the Approvability verdict.

alwaysApprove: routine paths

Every changed path must match for the agent to be skipped. A mixed PR goes through normal eligibility evaluation. Renames must match at both paths. Approval-file protection, neverApprove, and changes to CODEOWNERS by a non-owner take precedence. Correctness gates, ownership requirements, prerequisite waits, run mode, and Preview Mode still apply. An oversized diff does not block a fully covered PR because no eligibility agent needs to read it. A protected-path hold prevents automatic approval; it does not prevent merging. Use GitHub reviewer requirements for human review.

Waiting for other checks

Approvability always waits for Correctness and recognized external reviewers (Cursor BugBot and Greptile). How it waits for other checks depends on waitsFor. Both timeouts apply whichever way Approvability waits, and both start together when the wait begins. waitsForTimeout (default 20 minutes) limits how long checks may take to finish. waitsForDiscoveryTimeout (default 1 minute) limits how long they may take to appear. A check that appears is waited for until it finishes or waitsForTimeout expires, including time its run spends waiting on its own waitsFor or requires prerequisites. Without waitsFor, Approvability waits for the Check Run Agents it discovers running on the commit; you don’t need to list them. It keeps looking for newly started agents for as long as it waits. Because it can’t know in advance which agents will run, the discovery timeout is a minimum wait on every run: Approvability stops waiting once the discovery timeout has passed and no discovered agent is still running. An agent that only becomes discoverable after Approvability stops waiting is not included. If your agents are slow to start, raise waitsForDiscoveryTimeout; if they run long, for example because they wait on CI, raise waitsForTimeout:
With waitsFor, Approvability waits for the checks you name instead of automatically discovered Check Run Agents. waitsForDiscoveryTimeout limits how long a named check may take to appear, and the wait for named checks ends as soon as they have all finished. ["*"] waits for every check except Approvability’s own; as without waitsFor, the discovery timeout is then a minimum wait on every run. Automatic discovery and wildcard waits exclude agents that depend on Approvability, preventing circular waits. Avoid explicitly naming those agents as prerequisites: a named check is always waited for, including one listed alongside "*". Use check names from GitHub’s Checks tab. Waiting orders Approvability after other checks; it does not require them to pass. Approvability proceeds without a check that is missing or does not finish in time. If any named check has not appeared when the discovery timeout ends, Approvability stops waiting for all named checks, including ones still running. This differs from Check Run Agents, which skip when prerequisites are missing. Findings from Check Run Agents that finished in time are given to the eligibility agent as open review comments. They inform the verdict but do not block it on their own. Only Correctness findings at or above Minimum Blocking Severity block approval directly. Put expectations about failed checks and agent findings in your rules. The eligibility agent also receives each of the repository’s Check Run Agents with the result recorded for the pull request’s current head and base, including agents that finished before Approvability started waiting and agents it does not wait for. A rule can name an agent by its title, for example “approve only if Security Review passed”. An agent that has not finished, or has no check run for that head and base, is reported as unknown, not as passing. These results affect the verdict only where your rules refer to them. Dependency cycles are detected; affected custom agents skip with an error.

Check run conclusion

Workspace admins can set Check Run Conclusion to Neutral (default) or Failure per repository, in batch, or as a default for new repositories. An explicit conclusion in the file wins, including neutral. Preview Mode does not override this setting. With Failure selected, a Needs Human Approval verdict or outstanding blocking correctness findings can still fail the check. Preview Mode alone produces a neutral conclusion.

Using Approvability as a required status check

With conclusion: failure, require Macroscope - Approvability Check in branch protection to block on:
  • A Needs Human Approval verdict.
  • Outstanding correctness comments at or above Minimum Blocking Severity.
This is not a fail-closed gate. Protected paths, ownership holds, Preview Mode alone, missing reviews, limits, oversized diffs, errors, timeouts, and unusable results produce neutral or skipped conclusions. GitHub accepts both. Use GitHub required reviewers when a PR must remain blocked without approval. A human approval does not clear a failed status check. Resolve blocking correctness threads. For a Needs Human Approval verdict, push a new commit, rerun the check from GitHub’s Checks tab, or mention @macroscope-app.

Pricing

Preview Mode uses the same pricing as ordinary Approvability. Charges draw from the workspace’s Agent credits, including the shared 1,000 free credits per month. At the standard credit rate, 30 credits is $0.30; negotiated credit rates apply where agreed. Every check’s details shows its charge.