Git Hooks

Opt-in local last-resort gate before code reaches CI

The primer git hook is a developer convenience — it catches vulnerable package additions at commit time on the developer's machine. It is not a team enforcement layer. For team-wide enforcement, use barestripehq/primer-action@v1, which runs for every contributor regardless of local setup.

AspectGit Hookprimer-action@v1
Runs onDeveloper's machineEvery contributor, every push
SetupOpt-in per repoOne workflow file in the repo
Can be bypassedYes — --no-verifyNo (blocks merge)
Best forFast local feedbackOSS / team enforcement

Install

Run once in the root of each repository you want to protect.

primer hook install

This writes .git/hooks/pre-commit with a one-liner that calls primer hook check. The hook is marked executable automatically. It is idempotent — safe to re-run.

What primer hook check does

  1. Reads the git staging area (git diff --cached --name-only).
  2. Identifies any staged manifest or lockfile from the monitored list.
  3. Parses the diff for newly added package entries only.
  4. Scans each new package against OSV (--direct-only for speed).
  5. Exits 1 on CRITICAL/HIGH findings, aborting the commit. Exits 0 on clean.

On Rust projects, the hook also runs cargo fmt --check and cargo clippy -- -D warnings before the vulnerability scan. Both must pass for the commit to proceed.

Monitored files

EcosystemFiles watched
Node.jspackage.json, package-lock.json, yarn.lock, pnpm-lock.yaml
Pythonrequirements.txt, pyproject.toml, uv.lock, poetry.lock
Gogo.mod, go.sum
RustCargo.toml, Cargo.lock

Scope: only changes in the staging area are scanned — not the full project tree. --direct-only keeps pre-commit latency under 1 second on a warm cache.

Example output

When the hook blocks a commit:

primer: scanning staged manifest changes...

⚠ pillow 9.0.0 (PyPI) — GHSA-56pw-mpj4-fxjw [CRITICAL]
  Heap buffer overflow in TIFF image parser
  Fixed in: 9.0.1

primer hook check: 1 blocking finding. Commit aborted.
  Fix: pip install "pillow>=9.0.1"
  To bypass: git commit --no-verify

Manual run

primer hook check    # scan staged changes without committing

Useful for pre-flighting before you reach the commit step.

Override

git commit --no-verify           # bypass the hook for a single commit
PRIMER_FORCE=1 git commit        # equivalent; hook exits 0 regardless of findings

--no-verify bypasses all hooks, not just primer. Use PRIMER_FORCE=1 when you want to skip only the primer check while letting other hooks run.

Policy file and gitignore

primer hook check also validates that .primer/policy.toml and .primer/ignore are not gitignored. If either file would be excluded by .gitignore, the hook exits 1 with a warning — these files must be committed so the policy travels with the repo.

primer hook check
# → error: .primer/policy.toml is gitignored — add an exception or remove the rule