A pull request security summary should open with a clear verdict, then say how many new findings were introduced, list only the ones that block the merge, and link to the rest. Reviewers should know in five seconds whether they need to act.
Why the summary matters
On a busy pull request, the summary is the only part most people read. If it is a wall of text, they scroll past. If it says "failed" with no reason, they ask in chat, and the security team becomes a help desk.
GitHub's documentation for code scanning shows one common shape: the check that holds the results is named, new alerts on changed lines appear as annotations, and a link opens the full branch view. It also notes that a check fails only when results reach a severity level you configure. The design idea is worth copying for any tool: a verdict, the new items in place, and a link to everything else.
A template
- Verdict line. "Passed", "Passed with warnings" or "Blocked", in plain words.
- Counts. "2 new findings in this change. 0 blocking."
- Blockers. Each one with file, one line of why, and the fix action.
- Warnings. Collapsed by default.
- Scope note. "Existing findings are not shown. 14 open in this repository." with a link.
- Help. A link to dismiss, request an exception, or report a false positive.
Example
Blocked. 1 new blocking finding.
payments/client.pyline 72: a request is made with certificate checks turned off. Re-enable verification or request a dated exception.
2 warnings collapsed. 14 existing findings are tracked on the repository page.
Anti-patterns
| Anti-pattern | Why it hurts | Better |
|---|---|---|
| "Security check failed" with no reason | Forces a question | State the blocker and the fix |
| Listing every existing finding | Penalizes the author for old code | Show new findings, link the rest |
| Raw scanner output pasted in | Unreadable | Summarize and link |
| Different wording from the IDE | Breeds distrust | Use one message set |
| A neutral status for a blocking issue | Easy to merge by mistake | Make the status reflect the rule |
Handle the edge states
Scanner error. If the tool could not run, say "Could not scan" and do not show a green check. A skipped job that passes is a quiet hole, as described in can a skipped security job pass a required check.
Partial results. Say what was covered and what was not.
Timeouts. Report them as a state, with a retry action, not as a pass.
Keep it short and stable
A summary that changes shape every month trains people to ignore it. Fix the layout, change the content only. Keep the whole thing under a screen when possible.
Measure
Track how often reviewers ask what a failing check means. If it is common, rewrite the verdict and blocker lines. Track time from a blocked status to a resolved one as well.
Safeguard supports pull request policies and gates, so the verdict can follow a rule you define. See the gate pull request demo and the free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen. Check what the verdict says and how quickly you can find the blocker.
Quick check
Should the summary be a comment or a check status?
Use both sparingly: a status for the verdict and one summary comment that updates in place. Avoid a new comment on every push.
How long should it be?
Short enough to read without scrolling in the common case. Collapse the detail.
Sources
Last reviewed: 19 October 2026.
