heydeer
Sign in
Best practices

Teams with human reviewers

Use this setup when people review every pull request before it merges. HeyDeer checks the details first, so your reviewers can focus on design and product decisions.

Recommended setup

A pull request opens
HeyDeer reviews the details
The author fixes the findings
A reviewer checks the design and merges
  1. In Workspace settings → Review rules → When to review, select On every push. See Automatic reviews.
  2. Under Publish results, turn on Fail the check when issues are found. See The HeyDeer Review check.
  3. In GitHub’s branch rules for main, require the HeyDeer Review check. A pull request then merges only after HeyDeer reviews its latest commit and its findings and earlier concerns are fixed or declined.
  4. Ask reviewers to start reading a pull request after its HeyDeer Review check passes. They can then focus on design, product behavior and questions HeyDeer lists under Needs clarification.
Some checks were not successful
HeyDeer Review — Review found issues that need attention
CI / test — Successful
Merging is blocked
With the check required, a pull request can’t merge until its findings are fixed or declined.

A commit HeyDeer doesn’t review automatically, for example once the pull request reaches Maximum automatic reviews per PR, also blocks merging until someone requests a review. See Troubleshooting.

Optional: approve routine changes automatically

Turn on Automatic approval and keep PRs HeyDeer may approve at Low- and medium-risk PRs. HeyDeer then approves routine pull requests once no findings remain. High-risk pull requests wait for a person, and the review says why.

With 1 required approval in your branch rules, routine pull requests can merge without waiting for a reviewer. Turn on Dismiss stale pull request approvals when new commits are pushed, so every approval covers the latest code.

Write your standards as checks

A requirement your reviewers keep repeating in comments belongs in a check. Add a Markdown file to .agents/checks/ for each requirement, and HeyDeer applies it to every pull request that changes matching files. See Repository checks.

.agents/checks/migrations.md

---
files: "migrations/**/*.sql"
---
The previous release keeps running while a migration
deploys. Report a migration that:

- drops or renames a table or column that code on the
  base branch still uses;
- adds a NOT NULL column without a default;
- creates an index on an existing table without
  CONCURRENTLY.

What HeyDeer takes on

  • Details and edge cases. HeyDeer checks error handling, boundary values, concurrency and the callers a change breaks on every pull request.
  • Accurate on the details. On 1,000 internal pull requests, HeyDeer reviewed detailed correctness more accurately than human reviewers.