Every advisory banner PullGuard prints, what it means, and what to do about it — plus how to tell a deliberate zero from a broken setup.
pullguard doctor
Most "why didn't PullGuard do X?" questions are answered by the environment, not the code.
doctor checks it in one command — read-only, and your license key is always masked in its output:
pullguard doctor . # human-readable
pullguard doctor . --json # machine-readable
.driftrc.yml was found and whether it parses.It exits non-zero only when a check failed (a scan would run degraded), so you can use it as a CI setup gate.
When a scan can't run at your paid tier it says so at the top of the report and degrades to the free tier for that one scan — your subscription is never affected by a failed check.
The banner names the cause. Network: your runner could not reach
pullguard.dev/api/validate — check the runner's outbound HTTPS allowlist or firewall.
Service error: usually a brief outage on our side; the next scan retries automatically.
Persisting? hello@pullguard.dev.
Scans run at the free tier until renewal. A warning appears in reports for the last 14 days before expiry so this never lands as a surprise mid-sprint.
In GitHub Actions this is automatic. In other CI or local runs, set
PULLGUARD_REPO=<org>/<repo> (or scan inside a git clone with an
origin remote).
The Team plan covers 10 distinct repositories; the 11th+ scans at the free tier while your existing repos are unaffected. Free a slot via hello@pullguard.dev or upgrade to Enterprise for unlimited repos.
Not an error — it's the honesty line. Deep security (taint tracking), supply-chain/CVE, AI-era and compliance checks are partial or absent on the free tier, and category grades reflect only the checks that ran. A clean free-tier scan is not a security clean bill.
No. The scan runs entirely on your runner, and every call it makes to our service has a fallback: licence validation falls back to the free tier for that one scan, the rules bundle falls back to the signed catalogue built into the scanner, and the optional report upload is best-effort — a failed upload is logged and never fails the job. Two things are worth knowing so an outage stays invisible.
In branch protection, make the workflow job that runs the PullGuard Action the required
status check. The PullGuard check run with inline annotations is created by the PullGuard GitHub
App after the opt-in report-to-app upload — during an outage that upload fails, the build
still passes, and the check run simply never appears. If that check run were the required one, pull
requests would wait for a check that is not coming. The workflow job always reports, pass or fail.
If your runner cannot reach pullguard.dev to validate an online (pg_live_) key,
that scan runs the 14 free analyzers and the report says so in a banner. That is reduced coverage, not a
clean bill of health: the taint, supply-chain and AI-era analyzers did not run on that scan. If you need
full coverage regardless of our availability, use an offline licence key — it makes no network call at all
(see air-gapped & offline runs).
Large repositories can exceed the default scan caps. PullGuard never truncates silently: the report's
scan-coverage note states exactly how many collected files were never read, and
pullguard doctor predicts it before you scan. To widen coverage, raise the caps in
.driftrc.yml:
maxFiles: 10000 # collection cap (traversal)
maxFilesRead: 10000 # read cap — only read files are analyzed
maxDepth: 20 # directory depth
One more limit is per file: a code file over 500 KB (a configuration or data file over 100 KB) is not read, because such files are almost always generated bundles. The report names any code file it skipped this way, so a large first-party file is never silently unread — split it, or exclude a generated bundle explicitly.
On a very large monorepo, scanning per-package usually beats one giant scan. Full reference: Configuration.
Very occasionally a single file — usually a generated, minified or otherwise pathological one — makes one analyzer take far longer than the rest of the repo put together. First, confirm it is one file: re-run with that path excluded.
exclude:
- "**/vendor/**/*.min.js" # the usual suspects: generated + minified files
If you would rather PullGuard handle it for you, turn on worker isolation. Each analyzer then runs in its own worker thread with a per-analyzer time limit: one that overruns is stopped, and the scan finishes with the rest of the results. It is opt-in because it is a different execution path — the findings are identical either way, and it costs a little start-up time per scan.
analyzerIsolation: worker # .driftrc.yml — or PULLGUARD_ANALYZER_ISOLATION=worker for one run
The per-analyzer limit defaults to 180 seconds. On a repository of more than 10,000 files or 150 MiB of
source, the limit for the built-in security analyzers grows with the repository in the same proportion as the scan
budget (up to 450 seconds, and never past what is left of the scan budget), so a large repository's security
analysis is not stopped for its size. Setting PULLGUARD_SCAN_TIMEOUT_MS turns this off. If an analyzer is
stopped that you believe was doing real work, set PULLGUARD_ANALYZER_TIMEOUT_MS — an explicit value
applies to every analyzer, and it is clamped to 5–600 seconds, so the limit can never be switched off
entirely.
A stopped analyzer is never hidden: the report lists it under incompleteAnalyzers, the PR comment
carries the partial-scan banner, and the absence of its findings must not be read as "clean".
pullguard doctor tells you which mode a repo resolves to, and warns if worker was asked
for but is unavailable (in which case the scan runs inline).
Work through these in order — in our support history they explain nearly every case:
pullguard doctor shows the resolved tier and
analyzer count for the exact environment your scan uses.
PULLGUARD_OFFLINE=true is the one switch: every external call stays local (signed
embedded rule fallbacks, local CVE database, skipped freshness sweeps). Online
pg_live_ tokens cannot validate without network — air-gapped deployments use offline
keys instead. Details and the full egress disclosure:
Deployment & data sovereignty.
PullGuard's own calls (licence validation, the signed rules bundle, advisory lookups, the results
upload) honour HTTPS_PROXY, HTTP_PROXY and NO_PROXY from v1.5.18. The
published image is set up for it and the Action forwards your runner's proxy variables into the
container. From the command line, PullGuard turns proxy support on for itself when one of those
variables is set; to opt out, set NODE_USE_ENV_PROXY=0. A scan writes nothing to the home
directory, so a read-only HOME in a container is fine; only pullguard db update writes
there, and only when no database path is configured (the image keeps its database at /app/db).
Windows checkouts (CRLF line endings) are first-class: our detection suites run every fixture under both LF and CRLF, so results do not differ by checkout platform.
The Action exposes three outputs per scan — score (0–100, lower is better),
grade (A–F), and findings (count) — usable in later workflow steps:
- name: PullGuard
id: pullguard
uses: pullguard-dev/pullguard-action@v1
- name: Use the result
run: echo "Grade ${{ steps.pullguard.outputs.grade }} (score ${{ steps.pullguard.outputs.score }}, ${{ steps.pullguard.outputs.findings }} findings)"
The full report lands in three places per run: the PR comment, the workflow's Step Summary, and the
pullguard-report artifact (self-contained HTML report + over-time dashboard + SARIF).
Findings past their configured age budget are flagged via the sla config block — see
Configuration.
Email hello@pullguard.dev — attaching the output of
pullguard doctor (keys are masked automatically) answers most questions in one round trip.