> ## 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. # Approvability > Auto-approve low-risk PRs that pass code review 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: ```markdown theme={null} --- 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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging). `failure` makes the check hard-block merge via [required status checks](#using-approvability-as-a-required-status-check) — see caveats before enabling. | | `waitsFor` | none | Check run names that must complete before approvability runs. Supports `["*"]` wildcard to wait for all check runs. See [Waiting for Other Checks](#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 and any [Check Run Agents](/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:** ```yaml theme={null} --- 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):** ```yaml theme={null} --- 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): ```yaml theme={null} --- 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 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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging) 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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) 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](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) 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.