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: failure
---

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) means the check is advisory and never blocks merging. failure makes the check fail, allowing you to enforce approvability as a required check via branch protection rules.

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

​
Making approvability a required check

Set conclusion: failure in front matter, then add Macroscope - Approvability Check as a required status check in your branch protection rules. PRs that need human review will fail the check and block merging until a human approves.
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.