Skip to main content
Disabled by default. Enable per repo in Settings → Repos → Approvability.
Approvability

​
How It Works

When a PR is opened or updated, Macroscope runs two checks. Both must pass for auto-approval. If either fails, 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. Approvability

​
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

FieldDefaultDescription
tools[]Additional tools for the approvability agent. The agent always has file browsing and git tools; this field adds more capabilities.
conclusionneutralControls 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.
waitsFornoneCheck run names that must complete before approvability runs. Supports ["*"] wildcard to wait for all check runs. See Waiting for Other Checks.
waitsForTimeout20How 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 and any Check Run Agents before making its decision. Use waitsFor to also wait for additional CI steps — for example, external review tools, linters, or deployment checks 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:
ScenarioWhat happens
Prerequisites completeApprovability proceeds with its eligibility assessment, considering review comments posted by the waited-for checks.
Prerequisite not found after 60 secondsThe 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 timeoutApprovability proceeds without waiting further. Increase waitsForTimeout if the step is slow.
Circular dependencyDetected 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 regardless of waitsFor — this field controls additional prerequisites beyond the built-in correctness wait. 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

  1. Enable Approvability in Settings → Repos.
  2. (Recommended) Add a CODEOWNERS file to your repo.
  3. (Optional) Add a .macroscope/approvability.md file with custom eligibility rules and front matter configuration.
Macroscope cannot approve its own PRs.