A security comment on a pull request should say what is wrong, where, why it matters in this code path, how to fix it, and how to dispute it. If a developer cannot act on the comment in under two minutes, it is noise. Short, specific and fixable beats complete and vague.
Why most scanner comments get ignored
Engineers read a pull request comment the way they read a review from a teammate. If it cites a rule ID, a CVSS number and a link to a generic advisory, it reads like a form letter. The reader still has to work out which line, which package, and whether it applies.
The fix is not fewer findings. It is a better template, applied the same way every time.
The six parts of a comment engineers act on
| Part | What to write | Why it helps |
|---|---|---|
| Headline | One sentence in plain words: "User input reaches a SQL query without parameters" | The reader gets the point before opening a link |
| Location | File, line, and for dependencies the package and version | No hunting |
| Context | Is the code reachable from an entry point? Is the vulnerable function called? | Separates real risk from theoretical risk |
| Fix | A concrete change: the safe version, or a code diff | Turns a finding into a task |
| Effort | Rough size: one line bump, or a refactor | Lets the author plan |
| Dispute path | How to mark it a false positive, with a required reason | Keeps trust when the tool is wrong |
What to leave out
Leave out a wall of CVE references on the first screen, a repeat of the same finding on every changed file, and a severity label with no explanation. CVSS is a measure of severity, and the specification itself says consumers should supplement the base score with temporal and environmental scores. A bare "9.8" says little about your code.
Collapse long background into a link or a fold. Keep the comment itself short.
Volume matters as much as wording
Ten comments on a small change teach people to scroll past all ten. Cap the number of inline comments per pull request, show the highest priority first, and put the rest in a summary. Comment only on code the author touched. Old findings in untouched files belong in a backlog, not in someone's review.
A quick test for your own tool
Open the last five comments your tool posted. For each one, ask whether a developer who has never seen the rule could fix it without leaving the page. Count how many pass. If fewer than four do, change the template before you add any more checks.
Try it yourself
Click through it at your own pace, or open it full screen. Look at what the pull request check reports and how much a reviewer has to read.
Safeguard posts policy gate results on pull requests and can open fix pull requests, which are off by default. You can see what a scan reports on your own project with the free scan.
Quick check
How many security comments per pull request is too many?
There is no fixed number. A practical test is whether authors address most of them. If they dismiss more than they fix, lower the cap and raise the bar for what gets posted.
Should the comment include the CVSS score?
It can, as one line of context. Lead with the plain description and reachability, because the score alone does not tell the author what to do.
Sources
Last reviewed: 19 October 2026.
