First decide whether the scanner is failing (a tool error) or finding (a real result). Tool errors get a time boxed investigation and a documented bypass. Real findings follow your normal exception path. Never remove the gate silently, and always record who approved any bypass and when it ends.
Two different problems
A tool failure means the job crashed, timed out, could not download its database or hit a rate limit. A blocking finding means the scanner worked and your policy said no. They need different responses, and mixing them causes bad decisions at 5 pm on a release day.
The ten minute triage
- Open the job log. Look for the exit code and the last message.
- Check whether one repository or all of them fail. All of them suggests a shared cause such as an expired token, a data download problem or a runner change.
- Check for a recent change: scanner version, policy, base image, network rules.
- Re-run once. A single success suggests a transient fault.
- If the cause is not clear, move to the bypass decision.
Exit codes are worth learning. Our guide to how scanner exit codes fail a CI pipeline covers how scanner exit codes decide whether a pipeline fails. Make sure yours separates a finding from a tool error.
The bypass decision
| Situation | Suggested response |
|---|---|
| Tool error, urgent release | Time boxed bypass approved by the scanner owner, with a ticket |
| Tool error, no urgency | Fix first, no bypass |
| Real critical finding | Normal exception process, not a bypass |
| Real low finding blocking everything | Review the policy threshold, not the individual PR |
A bypass should have an owner, a reason and an expiry. Without those, it becomes the new default.
Open source versus managed differences
With open source tooling, your team usually diagnoses the fault, reads the issue tracker and may patch or pin. With a managed platform, the first step may be the vendor status page and a support ticket, so know the support path before you need it. Our post on support terms in a security tool contract lists what to ask.
After the incident
Within a week, write a short note: cause, time to detect, time to restore, and one change that prevents a repeat. Typical changes are pinning the scanner version, caching the database, alerting on job failure rates, or adding a fail open rule for a clearly defined error class. Be careful with fail open rules, since they are a policy decision that belongs to the owner and security lead, not to whoever is on call.
Keep a runbook
Store these steps next to the pipeline configuration. Include contact names, the bypass approval rule and the expiry convention.
Safeguard includes pull request gates and policies, with a free scan at gold.safeguard.sh/scan if you want to see how results are presented.
Try it yourself
Click through it at your own pace, or open it full screen. See how a gate reports a blocking result, then think about how your team would tell that apart from a failed job.
Quick check
Should we turn the gate off while we investigate?
Prefer a time boxed, approved bypass for the affected repositories over disabling the gate for everyone.
Is a scanner timeout a finding?
No. It is a tool error. Treat it separately and fix the cause.
Last reviewed: 19 October 2026.
