Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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