Use an inline comment when a finding is high confidence, sits on a line the author changed, and has a clear fix. Use one summary comment, or a check run summary, for lower confidence items, findings outside the diff, and counts. Inline is for action. Summary is for awareness.
What each format does well
An inline comment appears next to the code, so the author sees the cause and the message together. It also creates a conversation thread that has to be resolved, which adds friction. That friction is worth it when the finding is real and slightly costly to ignore.
A summary comment sits in the conversation tab or in the check output. It can carry a table, counts and links. It cannot be resolved line by line, which makes it better for information than for demands.
A simple decision table
| Finding trait | Inline | Summary |
|---|---|---|
| On a changed line | Yes | Optional |
| Outside the diff | No | Yes |
| High confidence, fix known | Yes | Link only |
| Low confidence or heuristic | No | Yes |
| Many similar hits | First one, rest grouped | Full list |
| Informational, no action | No | Yes |
The rule behind the table is that every inline comment should be something you would be comfortable making a developer respond to.
Why summaries need a home
GitHub Actions can write Markdown to a job summary file, and the platform combines each step's summary into one page on the workflow run. Each step summary is capped at 1 MiB, and up to 20 step summaries show per job. That is plenty for a findings table, so there is no reason to paste a long list into a comment thread.
Watch for duplicates
The worst pattern is the same finding showing up inline and in the summary and again in a separate annotation. Pick one primary surface per finding and link to the others. Duplicates multiply notifications and teach people that the bot repeats itself.
Where your tooling allows it, update a single summary comment in place on each push instead of adding a new one. A thread with twelve near identical bot comments is a thread nobody reads.
Try it yourself
Click through it at your own pace, or open it full screen.
Look at how each code finding is tied to a file and line, then decide which ones you would put inline.
Where Safeguard fits
Safeguard provides code and dependency scanning with reachability analysis, which helps decide which findings deserve an inline comment. Try the free scan on a repository to see the output.
Quick check
Can I use both formats for the same finding?
You can, but link one to the other. An inline note for the line and a summary row for the count is fine. Two full explanations is noise.
Where should findings outside the diff go?
In a summary or a backlog report. Inline notes on files the author did not touch are rarely acted on in that pull request.
Sources
Last reviewed: 19 October 2026.
