Not every change needs a person
With a review policy on, Coderbuds reads the files each pull request changes and says how much review it needs: none for docs and tests, an AI review for a small code change, a person for anything larger or riskier. Reviewers spend their time where a mistake costs something, and the rest stops waiting in the queue.
An AI review means a reviewer you add, such as the Claude workflow below. Coderbuds' own quality score never counts as the review.
The three policies
A team owner picks one under Team settings → Code review:
- Skip trivial changes — changes that are only docs or tests need no review; everything else gets one.
- Review by risk — trivial changes need no review, small code changes need an AI review, and changes over your size standard or in your sensitive paths need two people.
- AI review for everything — trivial changes need no review, and every other change needs only an AI review. It's for a team whose coding agents fix what the AI review finds and merge their own pull requests. See what still needs a person.
Every team starts on Skip trivial changes; choose Off to stop it. The decision applies from the next push. Changing the policy is recorded with who changed it, and announced in your Slack channel.
The risk grade
The comment grades how risky the change is in itself, the same whatever your policy, with the reason that set the grade. The line under it says what your policy asks for, and why only when that differs from what the risk alone would ask.
- ⚪ Minimal — only docs or tests.
- 🟢 Low — a small code change (up to 50 lines and 5 files), away from anything a person always reads.
- 🟠 Elevated — more code than an AI review is trusted with, or the author's first change to the repository.
- 🔴 High — something in what still needs a person, a path your team marked sensitive, over your size standard, or something the analysis flagged as hard to undo, swallowing an error or weakening a safeguard.
The four answers
| Says | Met by |
|---|---|
| ✅ No review needed | Nothing. Merge when CI passes. |
| 🔎 Needs an AI review | An AI review passing on the latest commit, or one person's approval. Once it has, the comment says AI review passed. |
| 👀 Needs a review | One person's approval. |
| 🔒 Needs a careful review | Two people's approval. |
The author, bots and Coderbuds itself never count. A request for changes holds the pull request until that reviewer approves.
What still needs a person
Under Skip trivial changes and Review by risk, these always get a person:
- CI workflows, CODEOWNERS and the instructions coding agents follow (
CLAUDE.md,AGENTS.md,.cursor/…). A pull request's own copy of these is what reviews it, so it cannot review itself. - Dependency manifests and lockfiles, built output, secrets (
.envfiles, keys) and infrastructure (Dockerfiles, Terraform, Kubernetes). - Database migrations, sign-in and permissions code, and billing code.
- A first change to the repository by its author.
- A change Coderbuds' analysis flags as impossible to undo, as swallowing its own errors, or as weakening a safeguard — widening access, dropping a check, or logging secrets or personal data.
Under AI review for everything, only the first of these still gets a person: CI workflows, CODEOWNERS and agent instructions. The rest need only the AI review, and the pull request names what would have asked for a person.
A change a coding agent reported writing that nobody has read never skips review: it needs at least an AI review, and a person under Skip trivial changes. Docs alone are the exception, since nothing in them runs.
Set it up
- Choose a policy. Review by risk is the usual start. Each pull request gets a review line on the Coderbuds comment and a Review policy check. Nothing is held yet.
- Add an AI review. The quickest is the Claude workflow. Claude Code Review or an AI reviewer you already use also count — see which reviews count. Settings shows the last one Coderbuds saw.
- Watch the Review tile on the Overview tab's Delivery card for a week or two. Does the policy call changes the way your team would?
- Make it the gate. Turn on Hold merges until the review is in and add Review policy as a required check on GitHub — see Making it the gate.
A coding agent can do this for you: get-review-policy-tool and set-review-policy-tool on the Coderbuds MCP server read and set the policy, and hand back the workflow to commit.
Which AI reviews count
Coderbuds' own analysis never counts as the review — it does not grade its own homework. One of these has to pass on the latest commit:
- The Claude workflow below, reporting a pass.
- Claude Code Review, Anthropic's managed reviewer for Team and Enterprise plans. It never approves; Coderbuds reads how many important findings it reported, and none counts as a pass. Nothing else to set up.
- An AI reviewer's approval, from Copilot, CodeRabbit, Greptile, Graphite. Copilot only approves where your organisation has turned that on.
- A CI check named
AI reviewthat passed. Any tool that runs as a job works, as long as the job fails when the review finds a problem — one that always passes is no review. This one only counts while merges are not held: any workflow can post a check under any name.
Where merges are held and the policy says an AI review is enough, Coderbuds approves the pull request once one passes — naming the reviewer and what it said — and takes the approval back if a later push needs more.
The Claude workflow
- Add an
ANTHROPIC_API_KEYrepository secret (Settings → Secrets and variables → Actions). - Save the workflow below as
.github/workflows/ai-review.yml. It is the one Coderbuds runs on its own repository. - Open a pull request. The job passes or fails on Claude's verdict, and the verdict goes in the Coderbuds comment. Anything Claude found on particular lines is posted as one review from Coderbuds' account, headed AI review · Claude. After a push, the earlier review folds into a link to the new one.
The workflow only reads the pull request. It proves which repository it runs in with GitHub's own OIDC token, so there is no Coderbuds secret to add.
Show the workflow
name: AI review
# Claude reads each pull request and passes or fails this job. A check named
# "AI review" that passes on the latest commit meets Coderbuds' AI-review tier,
# so small, low-risk changes no longer wait for a person. It fails only for a
# defect worth stopping for; style and taste are comments, not failures.
#
# It then tells Coderbuds what it found, proving which repository it runs in
# with GitHub's own OIDC token — there is no Coderbuds secret to share.
# Coderbuds posts Claude's findings as one review from coderbuds[bot], headed
# "AI review · Claude", and — where the team holds merges and its policy says
# an AI review is enough — approves the pull request. The workflow itself can
# only read the pull request: nothing it sends can approve anything.
#
# Needs one repository secret: ANTHROPIC_API_KEY.
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
concurrency:
group: ai-review-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
ai-review:
name: AI review
if: github.event.pull_request.draft == false && github.actor != 'dependabot[bot]'
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
contents: read
pull-requests: read
id-token: write
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 1
- name: Review with Claude
id: review
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
# The workflow's own token, so the Claude GitHub App is not needed.
github_token: ${{ secrets.GITHUB_TOKEN }}
prompt: |
REPO: ${{ github.repository }}
PR NUMBER: ${{ github.event.pull_request.number }}
Review this pull request. The branch is checked out in the working
directory; read the diff with `gh pr diff` and open any file you need
for context. Follow CLAUDE.md if the repository has one.
Fail it only for a defect a careful reviewer would stop the merge for:
a bug, a security hole, data loss, a migration that cannot be undone
safely, or an error that is silently swallowed. Style, naming and
preference are never a reason to fail.
Do not post anything to GitHub. Return each finding instead: the file
path, the line number in the new version of the file (a line this pull
request adds or changes), whether it should block the merge, and what
is wrong and how to fix it, in a sentence or two. Leave out anything
you are not confident about.
Return a verdict of "pass" when nothing should stop the merge, and
"fail" when something should, with a short summary of what you checked.
claude_args: |
--allowedTools "Bash(gh pr diff:*),Bash(gh pr view:*),Read,Grep,Glob"
--json-schema '{"type":"object","properties":{"verdict":{"type":"string","enum":["pass","fail"]},"summary":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"line":{"type":"integer"},"blocking":{"type":"boolean"},"body":{"type":"string"}},"required":["path","line","blocking","body"]}}},"required":["verdict","summary","findings"]}'
- name: Tell Coderbuds what the review found
if: steps.review.outcome == 'success'
# Coderbuds being unreachable must never turn Claude's verdict into a failed check.
continue-on-error: true
env:
RESULT: ${{ steps.review.outputs.structured_output }}
PR: ${{ github.event.pull_request.number }}
SHA: ${{ github.event.pull_request.head.sha }}
CODERBUDS_URL: https://coderbuds.com
run: |
report=$(echo "$RESULT" | jq -c --arg sha "$SHA" \
'{sha: $sha, verdict: (if .verdict == "pass" then "pass" else "fail" end), reviewer: "Claude", summary: (.summary // ""), findings: ((.findings // [])[:30])}' 2>/dev/null \
|| jq -nc --arg sha "$SHA" '{sha: $sha, verdict: "fail", reviewer: "Claude"}')
oidc=$(curl -sSf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=coderbuds" | jq -r '.value')
for attempt in 1 2 3 4 5 6; do
response=$(curl -sS -X POST -H "Authorization: Bearer $oidc" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d "$report" "$CODERBUDS_URL/api/github-actions/ai-reviews/$PR" || true)
echo "Coderbuds: $response"
if [ "$(echo "$response" | jq -r '.recorded // false' 2>/dev/null)" = "true" ]; then
break
fi
sleep 10
done
- name: Verdict
env:
RESULT: ${{ steps.review.outputs.structured_output }}
run: |
verdict=$(echo "$RESULT" | jq -r '.verdict // empty')
summary=$(echo "$RESULT" | jq -r '.summary // empty')
{
echo "### AI review: ${verdict:-no verdict}"
echo "$summary"
echo "$RESULT" | jq -r '(.findings // [])[] | "- \(if .blocking then "**Blocking**" else "Suggestion" end) `\(.path):\(.line)` — \(.body)"' 2>/dev/null
} >> "$GITHUB_STEP_SUMMARY"
if [ "$verdict" != "pass" ]; then
echo "::error::AI review did not pass: ${summary:-Claude returned no verdict}"
exit 1
fi
Already run an AI review job? Name it AI review (the job's name:) and make sure it fails on a finding. That is enough while merges are not held; to hold merges, the job has to report its verdict to Coderbuds the way the workflow above does.
Making it the gate
By default the Review policy check only reports: until its review is in it shows as neutral, which GitHub treats as passing. Turn on Hold merges until the review is in (Team settings → Code review) and it fails instead, then turns green the moment the review lands. While an AI review or the other checks are still running it shows as in progress, so it never fails before CI has finished.
- With branch protection or a ruleset (any paid plan, or a public repository): add Review policy as a required status check, and set required approvals to 0 if you want the policy alone to decide. Docs-only changes merge straight away, small ones once the AI review passes, the rest once a person approves. Dependabot pull requests get a passing check, so they are never stuck.
- Keeping one required approval instead? That works too: Coderbuds approves the changes your policy lets through without a person, and takes the approval back when a push needs more. Everything else still waits for a person.
- Using a merge queue? Coderbuds posts the Review policy check on each merge group too, so a required check never stalls the queue. In the ruleset, pin the check's source to the Coderbuds app so nothing else can pass it.
- Without protection (a private repository on GitHub Free): nothing on GitHub can stop a merge. The failing check is what GitHub shows instead of "Ready to merge", and anything that merges anyway is called out in Slack and on the Review tile.
A required check that never arrives holds a pull request too: if Coderbuds cannot read a change, it waits rather than waving it through. An admin can always merge past it. When GitHub Actions does not start your checks at all, because the minutes ran out or a payment failed, the Review policy check says so rather than calling it a failed review. Pushing again starts nothing, so a person's approval meets an AI review, and an admin merging past the checks is recorded as shipping without them.
Coding agents
- Before opening,
assess-change-fit-toolpredicts the review the change will need, names the files that make it need a person when splitting them out would lower the rest, and asks for a screenshot when the change touches what people see. The same call checks it against Coderbuds Standards. - On opening,
report-ai-usage-toolsays the agent wrote it, which is what lets Merge when ready apply. - After opening,
get-pull-request-review-toolanswers with onenext_step: fix what the AI review found, wait for it or for CI, ask a person, or merge. The agent does that and asks again.
On the pull request, Coderbuds keeps one comment up to date, and posts as a review only what needs one: its approval where your policy says an AI review is enough, carrying the AI review's suggestions on their lines, or the findings on their own where it does not approve. Where the agent merges when ready, the approval waits for CI and reads Approved — ready to merge, so a pull request the AI review passed gets the comment and one review.
Merge when ready
Off by default: people merge their own pull requests. Turn on Merge when ready (Team settings → Code review, under Hold merges) and the coding agent that opened a pull request merges it once it is ready:
- the review your policy asks for is in on the latest commit;
- every other check and commit status on that commit passed, and at least one reported;
- it is not a draft, and it targets your default branch.
- Only pull requests an agent reported writing. Anything a person opened is merged by hand, as before.
- Coderbuds decides; the agent merges. Coderbuds never merges and needs no write access to your code. Once a pull request is ready, it says so in a review, which wakes the agent whenever the last piece landed: Approved — ready to merge where an AI review met your policy, or Ready to merge after a person's approval, even hours later. The agent asks
get-pull-request-review-tool, which answersaction: mergewith the commit to merge, checks on GitHub that nothing has moved, and merges that commit only. - A comment never decides it. The agent merges because your team turned the setting on and Coderbuds says so, not because of what anyone writes on the pull request.
- It needs Hold merges. Only then does a green Review policy check mean the review is in.
- Merging may deploy. If a merge to your default branch deploys, turning this on lets changes reach production without anyone pressing merge.
When you are the reviewer
A coding agent running on your machine opens pull requests as you, and GitHub won't let you approve your own. Review it where you are working instead:
when the agent says a pull request is blocked on your review, it shows you the files that need you. Tell it you have reviewed them, and it records that with Coderbuds
(record-pull-request-review-tool), with your words.
Or, on GitHub, Files changed → Review changes → Comment → Submit review.
Where the agent reported writing the whole change, either counts as the review of that commit, shown as reviewed by the person who directed the agent, and a later push needs it again. It never counts on its own as a careful review, which needs somebody else too. It satisfies the Review policy check, not GitHub's own approval count, so small teams that rely on it should require the Review policy check and set required approvals to 0.
Where you see it
- On the pull request — one line on the Coderbuds comment, and a Review policy check beside CI that turns green once the review it asks for is in. The check's detail rates the change for Impact, Verification, Rollback cost, Error detection and Alignment, with the files behind each.
- In Slack — pull requests that need a person, anything that merged without the review it needed, and a Monday summary. These follow your Slack code review trigger: set it to when a pull request is opened (Team settings → Notifications), or the policy posts nothing beyond its announcement.
- On the dashboard — the Review tile on the Overview tab's Delivery card: how many changes went in on an AI review alone or needed none, the share that had the review they needed, and how often each kind was later reverted or fixed. That is the evidence for whether changes that skipped a person hold up.
How it stays honest
- A report counts only from the run for that pull request. The workflow proves itself with the token GitHub signs for the run, and Coderbuds takes it only from a
pull_requestrun for that same pull request, about its latest commit. Runs for other pull requests, pushes, manual runs and forks cannot vouch for it. - A pull request cannot change who reviews it. Anything under
.github/always needs a person, so a pull request that edits the review workflow is never passed by it. - The workflow can only read. Coderbuds posts the findings and gives the approval, and only for changes the policy lets through without a person.
- Where merges are held, a check counts only from the app that owns its name. A bare
AI reviewcheck is a signal, not a pass. - Every review says where it came from. What Coderbuds posts for an AI review links to the workflow run that did it.