Quickstart

Install the app#

1. Open the SuperDiffs GitHub App and choose Install.
2. Pick the account or organisation, then select repositories. Start with one repository. There is nothing to undo later, but a first impression on a repository you know well is worth more than coverage.
3. Approve the permissions. They are read access to code and metadata, plus write access to pull requests and checks — enough to read a diff and post a review, and nothing that can push a commit to your branches.

Get your first review#

Open a pull request, or push a commit to one that is already open. A review starts within a few seconds of the webhook and normally posts in one to three minutes, depending on how much changed.

To review a pull request that is already open and untouched since installation, comment on it:

@superdiffs review

Commands are honoured from people with write access to the repository. A command in the diff or in a code comment does nothing — see commands.

Read the review#

You should see up to three things:

• A summary comment — the change in a paragraph, a file walkthrough, and counts by severity. On the next push it is edited in place, so the thread does not fill with stale summaries.
• Inline comments — one claim each, with the concrete scenario that makes it a defect. If the fix is unambiguous, a suggestion block you can commit from GitHub.
• A check run — the review status, linked to the comments. Neutral by default: it reports, it does not block, until you make it required.

Disagree with a comment? Reply in the thread, or resolve it. A resolved finding is matched by content rather than by line number, so it stays resolved through rebases and force-pushes.

Add a config file#

Defaults are usable without any configuration. When you want to change them, commit this file at the repository root and open a pull request with it — the new settings apply from the moment it merges into the base branch.

# .superdiffs.yaml — commit this at the repository root.
# Everything is optional. These are the four knobs that matter on day one.

profile: balanced          # quiet (1 pass) | balanced (3) | thorough (5)
severity_threshold: minor  # critical | major | minor | nit

review:
  drafts: false            # don't review while the PR is a draft
  max_comments: 15         # lowest severities are dropped first

paths:
  filters:
    - "!**/dist/**"
    - "!**/*.gen.ts"

Every key is optional, and unknown keys are an error rather than a shrug: a typo in this file is reported on the pull request that introduced it instead of silently doing nothing. The full reference is in configuration.

Tune it in the first week#

If it says too much

• Raise severity_threshold to major. This is the single most effective change and it takes effect on the next push.
• Drop profile to quiet: one find pass, major and above, at most ten comments.
• Filter paths that are not really yours to review — generated clients, fixtures, migrations — with paths.filters.

If it misses things you care about

• Raise profile to thorough for five passes and nit-level output.
• Write the rule down in paths.instructions. “Every handler under src/api/** must be organisation-scoped” is the kind of thing a reviewer cannot infer from the diff, and the kind of thing it catches reliably once told.
• Run @superdiffs full-review on a pull request you already know has a bug in it. If we do not find a defect you can point at, that is a data point we want — the repository link plus what we missed, to the contacts on this site.

When nothing was posted#

In order of likelihood:

1. Nothing was wrong. A clean pull request gets a summary and no findings. Check the summary comment exists — if it does, the review ran.
2. The pull request is a draft. Drafts are skipped by default. Mark it ready, or set review.drafts: true.
3. Every changed file was skipped. Lockfiles, generated code, vendored trees and binaries never get comments. See limits and skips.
4. The title or author is on an ignore list. wip and [skip review] in the title are ignored by default.
5. The pull request is too large. Above the file limit we post the summary and ask you to opt in rather than reviewing 900 files badly.

@superdiffs config answers most of these directly: it posts the effective configuration for the repository, including which layer set each value.