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 file-level changes table showing what changed and why, so a human reviewer knows where to focus.

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 is prefixed with its type and area, so you can tell what kind of feedback it is: issue (bug_risk):, suggestion (performance):, issue (security):, and so on. Security comments carry 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.

Reacting to a comment

Every review comment carries a thumbs up and a thumbs down, and reacting teaches Sourcery what your team finds useful. Where many similar past comments were marked unhelpful, Sourcery suppresses similar new ones.

It’s a gradual signal. One downvote won’t silence a topic, it takes a consistent pattern across similar comments, and a comment can still appear where the surrounding code warrants it. A comment that goes outdated counts as positive: the code it flagged got changed, so the comment did its job.

Reactions are scoped per git organization, so a reaction in one repository carries across all of them. When the same request keeps coming up across reviews, a review rule states it outright instead of waiting for reactions to add up.

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.) It moves through 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 the review is skipped, so requiring it never blocks a merge. See security and pull request checks for how the Sourcery review check behaves.

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 reacts to every commit after that. The reaction is lighter than the first review. A re-review:

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.