Use check run annotations for many small, line level notes that belong to a check result, and pull request comments for a few findings that need a conversation. Annotations are capped per request and per step, so they suit a short list. Neither replaces a summary for the full picture.
What each surface is
An annotation is a note attached to a file and line, created by a check run. It shows up in the Files changed view and the check output, with a level of notice, warning or failure. It does not create a discussion thread.
A pull request comment starts a thread that people can reply to and resolve. It sends notifications and stays in the conversation.
Limits that shape the choice
GitHub's Checks API documentation says annotations are limited to a maximum of 50 per API request, and more can be added with further update calls that append to existing ones. The annotation level field is required and takes notice, warning or failure. The message can be up to 64 KB and the title up to 255 characters.
For GitHub Actions workflow commands, the documentation states a limit of 10 warning annotations and 10 error annotations per step. The syntax takes a file, line, end line and title.
So a scan that finds 300 issues cannot be expressed as 300 annotations in one step. You would be truncated or sending many API calls. That is a hint that 300 items belong in a summary or a report anyway.
A comparison
| Trait | Annotation | PR comment | Job summary |
|---|---|---|---|
| Tied to a line | Yes | Yes | No |
| Creates a thread | No | Yes | No |
| Starts a discussion | No | Yes | No |
| Volume it handles well | Dozens | A handful | Hundreds |
| Good for | Style, low severity | Real decisions | Full tables |
A layered pattern
- Put the top few high confidence findings in comments, capped.
- Put the next tier as annotations, so they show on the changed lines without threads.
- Put the complete list with counts in the job summary.
- Link the three together.
This gives the author an immediate short list, line level context for the next tier, and a full record.
Watch for duplication
The same finding as an annotation and a comment is noise. Assign each finding to one surface by severity and confidence. Keep the rule in one place, in your tooling configuration, so it is consistent across repositories.
Annotations and failure
Annotation level is not the same as pass or fail. A check can emit failure level annotations and still conclude as passing, depending on how it is written. Decide on the gate separately from the display, and document the mapping so no one assumes a red note blocks the merge.
Safeguard can report findings in SARIF form through its CLI, which fits code scanning workflows. See the free scan to view results.
Quick check
Can annotations replace comments?
For low stakes notes, yes. For findings that need a decision or a reply, comments are better because they can be discussed and resolved.
What happens past the annotation limits?
Send the rest in the summary or report. Do not keep adding calls to force every item onto the diff.
Sources
Last reviewed: 19 October 2026.
