To add a dependency scan to your CI pipeline, either connect the repository to Safeguard so the platform scans every change, or install the Safeguard CLI in a pipeline job and keep the results. The CLI reports findings. A policy gate in the platform is what decides whether a pull request should fail.
TL;DR
- CI (continuous integration) is the automatic build and test run that happens when someone changes code.
- Safeguard fits in two ways: connect the repo, or run the CLI inside a job.
- The CLI scan does not fail a build on its own. Gates do that.
- Start with warnings, then move to blocking once the noise is under control.
Definition: A gate is a checkpoint that a change must pass. A policy is a rule such as "no critical vulnerabilities". A gate applies one or more policies and can stop a deployment or a merge when they fail.
What are my two options for CI?
The Safeguard CI documentation describes two ways to fit into a pipeline.
| Option | What you do | Where the scan runs |
|---|---|---|
| Connect the repository | Add the repo as an integration in the platform | On Safeguard, as changes arrive |
| Run the CLI in a job | Install the CLI in a pipeline step and run a scan | On your build machine |
With the first option, nothing has to run inside your pipeline. The platform scans the repository and checks your policies and gates against the results. With the second, the scan runs on the machine that does your build, and you keep the results as build files.
Which should you pick? Connecting the repo is the simpler path and the one the documentation lists first among its recommended practices. Running the CLI makes sense when your code must not leave your own machines, or when you want the raw result files saved with each build.
You can do both. Many teams connect the repository and also save CLI results as an extra record.
What does a pull request gate do?
A pull request is a proposed code change that a teammate reviews before it joins the main code. It is the last easy moment to stop a risky package. Once it merges, undoing it takes more effort.
The Safeguard demo on this topic describes it simply. A Safeguard step runs, and the build fails when the scan finds vulnerabilities at or above the severity you choose.
The platform documentation adds the detail. Policies are rules that evaluate your SBOMs. They can be advisory or blocking. Gates are the checkpoints that enforce the policies. Each policy has an action:
| Action | What happens when the policy fails |
|---|---|
| Block | The gate fails |
| Warn | The gate passes, with a warning that names the policy |
| Notify | The gate passes, and a notification is sent |
The documentation lists conditions you can use in a policy, such as vulnerability severity ("no critical CVEs"), a CVSS score cap, an EPSS check for actively exploited flaws, license rules, component age and maintenance status. It also lists templates, including one named No Critical Vulnerabilities that blocks critical CVEs.
CVSS is a 0 to 10 severity score. EPSS is a score that estimates how likely a flaw is to be exploited soon. Our CVSS, EPSS and KEV FAQ explains both in plain terms.
How do I run the CLI in a pipeline job?
First, install the CLI in the job and pin a version, so a new release does not change a build without you noticing. The documentation shows this form:
curl -fsSL https://cli.safeguard.sh/install | SAFEGUARD_VERSION=<version> bash
Replace the version placeholder with the release you chose. You can list releases at cli.safeguard.sh/releases.
Second, put the scanner helper tools on the path. The scan uses two tools named syft and grype. A fresh CI runner does not have them, so install both before the scan step, or point the TOOLS_DIR setting at a folder that holds them.
Third, run the scan and save the output. Here is the GitLab example from the documentation:
safeguard-scan:
stage: test
image: ubuntu:24.04
script:
- apt-get update && apt-get install -y curl
- curl -fsSL https://cli.safeguard.sh/install | SAFEGUARD_VERSION=<version> bash
# syft and grype must be on the PATH before this step
- safeguard scan --dir . --output safeguard-results
artifacts:
paths:
- safeguard-results/
The same documentation page shows examples for GitHub Actions, Jenkins and Azure DevOps. The pattern is the same: install, scan, keep the results. The docs also say there is no published Safeguard GitHub Action, container image or pipeline plugin for the CLI yet, so you install it with the one line installer.
What do the exit codes mean?
An exit code is the number a program returns when it ends. Build systems treat zero as success.
- 0 means the scan ran, whatever it found.
- 2 means results were written but the vulnerability scan did not run. A script never mistakes that for a clean pass.
- 1 means the command itself failed, for example a bad option.
So a scan that finds ten critical flaws still returns 0. Please do not read that as "all clear". It only means the scan finished. To stop a build on findings, use a gate.
How can a job fail on a gate?
The policies and gates page says gates are evaluated by the platform on the scans it runs for your connected repositories. With policy outcomes turned on for your workspace, a command named safeguard ci scan with the wait option and a fail on gate option can fail a CI job when the gate fails. Check the current command help in your CLI build, because the docs say the help output is right if a page and the help disagree.
How do I roll out a gate without annoying everyone?
A gate that blocks on day one often gets turned off on day three. A gentler plan works better. For more ideas, see our posts on how to set up a vulnerability policy gate and on gates developers accept.
- Week 1: observe. Connect the repo or run the CLI. Do not block anything. Just look at the findings and note the top few.
- Week 2: warn. Create a policy with the Warn action for critical vulnerabilities. Developers see the message on their pull requests. Nobody is blocked.
- Weeks 3 and 4: fix the backlog. Clear the existing criticals. If you block while hundreds of old findings remain, every pull request fails for reasons the author did not cause.
- Week 5: block on new criticals only. Switch the action to Block. Because the backlog is gone, a failure now points at something the author just added.
- Keep an exception path. The documentation describes an exception workflow: a developer requests an exception, picks the policy and the finding, gives a business reason and an expiry date, an approver decides, and the audit trail records it.
An exception with an expiry date matters. Without one, "temporary" exceptions last forever.
What does a rollout look like with invented numbers?
The numbers below are invented to show the shape of a rollout.
A team has 12 repositories. On the first scan they see 90 critical findings across all of them. If they had blocked on day one, almost every pull request would fail.
Instead they warn for two weeks. During that time they fix the 90 down to 15 by upgrading packages. Three of the 15 have no fix yet, so they file exceptions with a 60 day expiry. They then switch the policy to Block. From that day, only new critical findings fail a pull request, and the typical failure points to a package added that same day.
The point is the order: clear, then enforce.
How can Safeguard help?
Safeguard offers these generally available capabilities for this job:
- Policies, gates and guardrails, with Block, Warn and Notify actions and an exception workflow.
- SBOM and dependency scanning, plus reachability analysis to rank what is worth fixing first.
- Autonomous remediation with fix pull requests, which is off by default and starts on Manual in every category.
- Compliance and evidence automation, so scan results can support your own review process.
The Safeguard CLI runs these scans on your own machine, and its assistant can also write code to apply fixes. You can try the free scan at gold.safeguard.sh/scan before you wire up anything. For the install steps, see our CLI guide. For general pipeline hygiene, see CI/CD pipeline security practices.
Try it yourself
Click through it at your own pace, or open it full screen.
Click through the eight steps and look for where you choose the severity that makes the build fail.
Quick check
Does the Safeguard CLI fail my build when it finds a vulnerability?
No. The scan command exits with 0 whenever the scan ran. The documentation says gating on findings is done by policy gates in the platform.
What should I pin in CI?
Pin the CLI version with the version setting on the installer, so a new release does not change your build under you. Update it on purpose, and keep the results as build files.
Why warn before blocking?
If old findings are still open, a blocking gate fails every pull request for problems the author did not add. Warn first, clear the backlog, then block on new findings.
What if one finding has no fix?
Use the exception workflow. Request an exception with a reason and an expiry date, get it approved, and review it when it expires.
Sources
- CI/CD Integration documentation
- Policies and gates documentation
- CLI usage documentation
- Fail the build on a pull request demo
- Safeguard Gold, Free Dependency Scan
Last reviewed: 19 October 2026.
