A failed security gate message should tell the developer four things: what rule failed, why it matters in one line, the exact change that will pass, and how to ask for an exception. If the message cannot do that, developers will route around the gate instead of fixing the problem.
Why message wording matters
A gate is only as useful as the next ten minutes after it fails. A red check with "policy violation: 3 issues" sends the developer to a dashboard, then to a wiki, then to chat. Each hop is a reason to disable the check. A good message keeps the developer in the pull request.
The template
| Part | Example |
|---|---|
| Rule | "Blocked: dependency has a known exploited vulnerability" |
| Where | "example-lib 1.2.3 in package.json, added by this pull request" |
| Why | "The flaw allows remote code execution and is listed as exploited." |
| Fix | "Upgrade to 1.2.9. This is a patch release, tests in the repo cover the affected calls." |
| Exception | "If you cannot upgrade, request a time-limited exception here: link. Include the compensating control." |
| Owner | "Questions: appsec-help channel" |
The package name and versions above are placeholders that show the shape of the message.
Rules of thumb
Name the change that caused it. Distinguish a problem this pull request introduced from one that was already in the main branch. Blocking someone for a pre-existing issue feels unfair and breeds resentment.
Show the smallest fix first. Patch before minor before major. If a safe upgrade exists, lead with it.
Be exact about severity and reasoning. "High" alone is thin. "High, reachable from the public checkout route" is actionable.
Separate blocking from advisory. Use different labels so a developer can tell which findings stop the merge and which are information. Review comment labels such as nit and optional follow the same idea of making intent explicit.
Keep it short. The check summary should fit on one screen. Link to detail instead of pasting a scan log.
Plan the exception path
Every gate needs a documented way through, with an expiry, an approver and a record. If the sole way past is to ask in chat, people will ask in chat at the worst time. A visible, boring exception path actually increases trust in the gate.
Test the message with a real developer
Before rolling out, give the message to a developer who has not seen the policy and ask: what would you do next? If the answer is "look it up", edit the message. Revisit wording after the first month, using the most common failure reasons.
Try it yourself
Click through the pull request gate demo and look at what information appears at the point where a change is blocked.
Click through it at your own pace, or open it full screen.
Safeguard policies, gates and guardrails can enforce these rules on pull requests. Start with the free scan at gold.safeguard.sh/scan to see which findings would trigger them.
Quick check
Should every failed gate offer an exception?
Almost always. A gate with no exception path pushes people to disable it. Make exceptions time-limited and recorded.
Where should the message appear?
In the pull request check summary or a bot comment, where the developer is already working.
Last reviewed: 19 October 2026.
