Anatomy of a review

Every Sourcery review has the same parts. Here’s what each one is, where to find it on the pull request, and what changes when you push more commits.

Summary

Sourcery writes a summary into the pull request description itself, under a Summary by Sourcery heading. It covers what the change does and where the risk is. Because it lives in the description rather than a comment, it stays at the top of the pull request as the conversation grows.

Sourcery writes the summary when the review runs; re-reviews don’t regenerate it. To refresh it, comment @sourcery-ai summary.

Reviewer’s guide

The reviewer’s guide is a comment that maps the whole change set. It opens with a short overview, then a table of what changed in each file and why.

For changes with non-trivial control flow, the guide can include a sequence diagram. Diagrams are on by default; use the Enable sequence diagrams toggle in the review settings to turn them off.

Inline comments

Inline comments are per-line feedback, posted as native review comments on the lines in question. Each comment starts with a label that says what kind of feedback it is, like issue (bug_risk): or nitpick (performance):. Security comments start with a 🚨 marker.

Where Sourcery can propose a concrete fix, the comment includes a suggestion block you apply with GitHub’s Commit suggestion button.

When a pull request removes code that a security scan previously flagged, the review also lists the findings it resolves, linked to the dashboard. See security and pull request checks.

Status check

On GitHub, every review reports a single status check called Sourcery review on the pull request’s head commit. (GitLab merge requests don’t get a status check; there, the review is the summary, guide, and inline comments.) The check reports one of these states:

In progress, while the review runs.
Success, when the review posts with no blocking issues.
Failure, when blocking security findings require changes.
Skipped, when a rate limit or the re-review cap applies.

Because the check posts on the head commit, you can add Sourcery review to a branch protection rule and require it before merge. The check posts even when Sourcery skips the review. Requiring it never blocks a merge. See security and pull request checks for how the Sourcery review check behaves.

Approval

Sourcery can approve a pull request, and a branch protection rule that requires an approval counts it. Sourcery approves when nothing it found is worth blocking on and the change doesn’t need a person’s judgement.

Turn it on or off with Let Sourcery approve pull requests in the review settings.

Linked issues

Sourcery uses related GitHub Issues as review context. For issues linked in the pull request description, it assesses whether the change actually addresses them. It also searches your repository for other issues that look related and links them in the reviewer’s guide.

Re-reviews

Sourcery reviews a pull request when it opens and re-reviews it after every commit. A re-review does less than the first one:

Re-checks each existing Sourcery comment against the new code and resolves the threads the new commits address.
Re-runs the security scans and posts any new findings as a fresh review.
Leaves the rest of the review in place. It doesn’t regenerate the summary, reviewer’s guide, or the full set of inline comments.

Automatic re-reviews are capped at five per pull request. Past the cap, Sourcery stops re-reviewing automatically and the check reports Skipped. Comment @sourcery-ai review to reset the counter and run a complete review from scratch. See commands for the rest of the command set.

Rate limits are separate from the re-review cap. Sourcery measures them in diff characters and skips a review when one is reached, and the limits vary by plan. See plans and pricing for the caps and how the budget works.