How to Make AI Code Review a Required Check on GitHub

To make AI code review a required check on GitHub, install an AI reviewer that reports results as a GitHub check run, let that check run once on a pull request, then add it under "Require status checks to pass before merging" in a branch protection rule or ruleset for your default branch. With Macroscope, the review posts as Macroscope - Correctness Check, and any Check Run Agent you write can be set to fail its check so GitHub blocks the merge until the problem is fixed.

TL;DR: AI code review as a required check on GitHub

• GitHub enforces required checks by name, through a branch protection rule or a ruleset.
• A check has to run before you can select it. Open one PR after installing Macroscope, then add its checks.
• Macroscope posts named check runs: Macroscope - Correctness Check, Macroscope - Approvability Check when enabled, and one per Check Run Agent.
• Check Run Agents can block merges with conclusion: failure and input: full_diff.
• Start non-blocking, then promote only the checks that prove reliable, ideally on high-risk paths.

How do GitHub required status checks work?

A required status check is a check name that GitHub insists must report a passing result on a pull request before the merge button unlocks. You configure it on a branch, usually your default branch, through either a classic branch protection rule or a repository ruleset.

Every CI job, linter and GitHub App that reports into the Checks tab produces a named check. When you mark a name as required, GitHub waits for a result with that name on the PR's latest commit. GitHub treats a successful, skipped, or neutral result as passing. A failing result, or a check that has not reported yet, keeps the PR blocked.

Because GitHub matches by name, a required check that never reports (because it was renamed, or only runs on some PRs) shows as "Expected" and blocks indefinitely.

Branch protection rules vs. rulesets

Branch protection rules are the older, per-branch settings; rulesets are the newer, layered version, and both support required status checks. Classic branch protection lives under Settings > Branches. Rulesets live under Settings > Rules > Rulesets, can target several branches at once, support a bypass list, and, depending on your GitHub plan, can be set at the organization level. If your organization already uses rulesets, add the AI check there; otherwise classic branch protection is the quickest path.

Why does the check have to run once before you can select it?

GitHub's status check picker only searches checks that have recently reported in the repository (GitHub's docs say within the last week), so a check that has never run will not appear. Install the reviewer, open a pull request so it posts its checks, then select them. The same goes for each new Check Run Agent.

Which check runs does Macroscope post on GitHub pull requests?

Macroscope posts its review as a GitHub check run named Macroscope - Correctness Check, posts Macroscope - Approvability Check when Approvability is turned on, and creates one more check run per Check Run Agent you define. All of them appear in the PR's Checks tab next to your CI.

Check run	What it does	Can it block a merge?
Macroscope - Correctness Check	The built-in AI code review. Finds bugs and posts inline comments, with suggested fixes, on the lines involved.	Requiring it guarantees the review ran before merge. To block on specific findings, use a Check Run Agent.
Macroscope - Approvability Check	Decides whether a low-risk PR is safe to auto-approve, and posts a GitHub APPROVE review when ownership, eligibility and correctness all pass. Off by default.	Optional. Its conclusion defaults to neutral (informational). Setting failure makes it hard-block through required status checks.
Macroscope - <agent title>	One per Check Run Agent, defined in a markdown file in your repository.	Yes, when the agent sets conclusion: failure.

The correctness review looks past the diff into the rest of the repository to check whether a change breaks code that depends on it. For how the review itself works, see how to set up AI code review on GitHub.

How do Check Run Agents block merges?

A Check Run Agent is a markdown file in .macroscope/check-run-agents/ on your default branch; set conclusion: failure and its check run fails when it finds a blocking issue, which GitHub enforces as a required check. Each agent is its own check, so you can require some and leave others advisory. A minimal merge-blocking agent, using fields from the Check Run Agents guide:

---
title: Security Review
model: claude-opus-4-6
reasoning: high
effort: high
input: full_diff
conclusion: failure
tools:
  - browse_code
  - git_tools
  - modify_pr
---

Perform a security review of this PR:

- Check for hardcoded secrets, API keys, or credentials
- Verify authentication middleware on new routes
- Check for SQL injection, XSS, or command injection vectors

If any HIGH severity issue is found, the check MUST fail.

Saved as .macroscope/check-run-agents/security-review.md and merged, this creates a check run called Macroscope - Security Review.

Three details decide whether the gate works:

• conclusion defaults to neutral, which reports but never blocks. Only failure makes a merge gate.
• conclusion: failure needs input: full_diff. The default incremental mode does not support failure.
• Agents are read from the default branch when a PR is opened, pushed to, or manually rerun, so a PR that edits an agent file cannot loosen the gate on itself.

Watch out for scoped agents and required checks

If you scope a required agent with include patterns, PRs that do not touch those paths never get the check, and GitHub may keep waiting for it. Agents with include globs do not run at all outside their scope, which saves cost and noise, but a required check that never reports blocks. Either require only agents that run on every PR and put path logic in the instructions ("if the PR touches src/payments/, check X; otherwise pass"), or keep path-scoped agents advisory. Test on a PR that touches nothing in scope before you rely on it.

How do I make AI code review a required check step by step?

Install Macroscope, let it review one pull request, then add Macroscope - Correctness Check (and any blocking Check Run Agents) as required status checks on your default branch.

Step 1: Install Macroscope and run it once

1. Install the Macroscope GitHub App on your organization and choose which repositories to connect. See the setup guide for the full flow.
2. Open a pull request in a connected repository.
3. Wait for Macroscope - Correctness Check to appear in the PR's Checks tab. If you need to trigger a review by hand, comment @macroscope-app review on the PR.

Step 2a: Require the check with a branch protection rule

1. In the repository, open Settings > Branches.
2. Add a branch protection rule (GitHub now labels it a classic rule) and set the branch name pattern to your default branch, for example main.
3. Check Require status checks to pass before merging.
4. Optionally check Require branches to be up to date before merging, so the check result reflects the code as it will actually merge.
5. In the status check search box, type Macroscope and select Macroscope - Correctness Check, plus any Check Run Agents you want to enforce.
6. Save the rule.

Step 2b: Or require the check with a ruleset

1. Open Settings > Rules > Rulesets and create a new branch ruleset.
2. Name it, and set enforcement to Active.
3. Under target branches, include the default branch.
4. Enable Require status checks to pass, add the Macroscope checks by name, and, if GitHub offers it, pin the expected source to the Macroscope app so another integration cannot satisfy the check with the same name.
5. Create the ruleset.

Step 3: Add a blocking Check Run Agent (optional)

1. Create .macroscope/check-run-agents/<name>.md with conclusion: failure and input: full_diff.
2. Merge it into the default branch.
3. Open a PR so the new Macroscope - <title> check reports once.
4. Return to the rule or ruleset from Step 2 and add the new check name.

Step 4: Confirm it works

Open a test PR the agent should fail and confirm the merge is blocked. Fix it, push, and confirm the block clears. Then open an unrelated PR and confirm it is not stuck waiting on a check that never ran.

Should AI code review block merges?

Sometimes. An AI check should block a merge only once you have watched it be right on your own pull requests, and usually only for high-risk paths; everywhere else it works better as a fast, advisory reviewer. Required checks are a blunt tool. Every false positive on a blocking check costs an engineer real time and teaches the team to resent the gate.

The case for making AI review required

• It guarantees the review happened. Requiring Macroscope - Correctness Check means no PR merges unreviewed, which matters more as coding agents open a growing share of PRs.
• Some rules are non-negotiable. Hardcoded secrets, unauthenticated endpoints, destructive migrations. A blocking agent enforces these on every PR, whoever reviews.
• It fits the existing workflow. A failing AI check behaves like a failing test.

The case against blocking everything

• False positives are expensive when they block. A wrong advisory comment takes seconds to dismiss. A wrong blocking check stops the merge until someone pushes again or reruns it.
• Judgment-heavy rules are noisy. "Is this abstraction appropriate?" is a fine advisory question and a poor merge gate.
• Unblocking takes a new run. Macroscope's Approvability docs note that a PR review approval alone does not clear a failing status check; a new commit or manual re-run is needed.

A rollout that works

1. Start non-blocking. Run agents with the default conclusion: neutral for a week or two and read what they flag.
2. Promote the reliable ones to conclusion: failure and add them to the required list.
3. Block only on high-risk code: security, auth, billing, migrations, infrastructure. Leave style checks advisory.
4. Keep Approvability informational at first. Its neutral default shows what it would have done. Many teams pair it with GitHub's native auto-merge. See what Approvability is.

What does running AI review as a required check cost?

Making a check required does not change what it costs; you pay for the review runs and agent work either way. Macroscope is usage-based, with no per-seat fees. Code review is $0.05 per KB of diff reviewed with a 10 KB minimum ($0.50 floor). Check Run Agents bill as Agent credits at $0.01 per credit, and every workspace includes 1,000 Agent credits per month. Every new workspace gets $100 in usage credit.

Each new push can trigger another review run. Spend controls (caps per review and per PR, monthly budget limits, turning off auto-review by repo or label, file exclusions) keep that predictable; default caps are $10 per review and $50 per PR, adjustable in Settings > Billing. See the pricing page and how to control AI code review costs.

Frequently Asked Questions

How do I make AI code review a required check on GitHub?

Install an AI reviewer that reports as a GitHub check run, open one pull request so the check reports, then go to Settings > Branches (or Settings > Rules > Rulesets), enable "Require status checks to pass before merging" for your default branch, and select the check by name. With Macroscope, require Macroscope - Correctness Check to guarantee every PR is reviewed before merge, and add any Check Run Agent set to conclusion: failure to block merges on the issues it finds.

What AI reviews my GitHub pull requests automatically?

AI code review tools installed as GitHub Apps review pull requests automatically when they are opened or updated. Macroscope is one: once installed, it reviews every PR in connected repositories, posts inline comments with suggested fixes, writes a PR summary, and reports Macroscope - Correctness Check in the Checks tab. Other tools in the category include CodeRabbit, Greptile, Cursor Bugbot and GitHub Copilot code review. The setup guide walks through getting the first automatic review.

Why can't I find the Macroscope check in the status check list?

GitHub only lists checks that have recently reported in the repository. Open a pull request, wait for Macroscope - Correctness Check to appear in the Checks tab, then search again. For a new Check Run Agent, merge its file to the default branch and let it run on one PR first.

Does a neutral Check Run Agent block the merge?

No. neutral is the default conclusion, and GitHub treats a neutral result as passing. The agent still posts its findings. Set conclusion: failure, with input: full_diff, to block.

Why does my blocking agent need input: full_diff?

The default input: incremental mode reviews only the files changed since the agent's last completed review of the PR, and it does not support conclusion: failure. A merge gate needs to judge the whole change, so set input: full_diff on any agent you make required.

What happens if the AI check is wrong and blocks a merge?

Fix the issue or adjust the agent's instructions, then push a new commit or re-run the check; an approving review alone does not clear a failing status check. If an agent is often wrong, move it back to conclusion: neutral until its instructions are tighter.

Can I require AI review only for certain directories?

Yes, carefully. An agent with include patterns does not run on PRs outside those paths, and a required check that never reports leaves GitHub waiting. Require an agent that runs on every PR and handles path logic in its instructions, or keep path-scoped agents advisory.

Can a pull request author weaken the AI check in their own PR?

Not for that PR. Macroscope reads Check Run Agent files from the default branch, so a PR that edits an agent file still runs against the version already merged. Approvability's default policy also escalates changes to .macroscope/ configuration files to a human reviewer.

Should I require Approvability as a status check?

Usually not at first. Approvability is off by default, and its conclusion defaults to neutral, which keeps it informational. Setting failure hard-blocks every PR it does not approve until a new commit or re-run, so most teams keep it neutral and rely on GitHub's required reviewers for human approval.

Does making AI review required cost more?

No. You pay for review runs and agent work either way: $0.05 per KB of diff reviewed ($0.50 floor), and $0.01 per Agent credit for Check Run Agents, with 1,000 credits included per workspace per month. Set per-review and per-PR caps in Settings > Billing.

---

Making AI code review a required check on GitHub takes minutes. Deciding which AI checks deserve to block takes longer, and it should: start advisory, promote what proves reliable, and keep blocking gates where a bad merge actually hurts. To try it, install Macroscope on your GitHub organization, and read the Check Run Agents guide to write your first gate.