Pre-push hooks

A pre-push hook runs locally each time you git push. SiteCMD's check command evaluates the configured website URL, not the source commit you are pushing. Use it for a running local or staging site; use sitecmd audit . --fail-on high when the hook must check source changes before deployment.

SiteCMD ships a hook installer in the CLI.

Install

The built-in installer writes .git/hooks/pre-push and overwrites an existing file there. It requires a checkout with a .git directory; linked worktrees with a .git file are not supported. It does not follow core.hooksPath. If your repository already has hooks or a hook manager, use hook chaining instead.

In an ordinary checkout with no existing pre-push hook, first initialize .sitecmd/ with sitecmd init, then run:

sitecmd check --install

This writes a script that calls sitecmd check when sitecmd is on PATH. If the binary is missing, the generated hook skips the check and lets the push continue. Run sitecmd check --install --strict to have it call sitecmd check --strict instead. Verify the command works in your hook environment; CI remains the enforcement layer for the whole team.

One thing to know: init doesn't write a score threshold, so a plain sitecmd check hook passes (and says so) until you give it something to enforce. Arm it one of two ways:

• Set "fail_under": 85 in .sitecmd/config.json for a score floor, or
• Install with --strict to add a fresh-scan regression gate. Any configured score floor still applies.

What the hook checks

The default mode is a score gate: sitecmd check compares your score against the threshold (--fail-under flag, else fail_under from config) and exits non-zero below it. To stay fast on every push, it reuses the cached .sitecmd/last-scan.json when it's less than 24 hours old and only re-scans when the cache is stale.

--strict is the regression gate: it always runs a fresh scan and fails when any failing check wasn't failing in the previous scan, on top of the threshold gate. The first strict run has no previous findings to compare, but it can still fail a configured score floor.

sitecmd check --strict

Useful when you want zero new issues, even if your absolute threshold isn't breached.

Customizing the threshold

The threshold defaults to fail_under in .sitecmd/config.json. Override per invocation:

sitecmd check --fail-under 85

The installer persists only the strict-mode choice, not --fail-under. Put a lasting threshold in .sitecmd/config.json, or pass it explicitly in your hook manager's command.

Repository policy

Follow your repository's rules for required hooks and exceptions. Resolve a failing check or obtain the maintainer's approval for an exception before bypassing a required gate.

When pre-push isn't enough

A pre-push hook runs only on the machine of whoever's pushing. If your team is split across machines, or if you want guarantees that hold up to "I forgot to install the hook," CI is still the right enforcement layer. Use both: pre-push for fast feedback at the developer's keyboard, CI for the trust boundary.

For CI setup, see Quality gates in CI.

Uninstalling

The hook is just a file at .git/hooks/pre-push. To remove it, delete the file:

rm .git/hooks/pre-push

If you have other hooks chained in the same file (some teams use husky or lefthook for hook orchestration), edit the file instead of deleting it.

Hook chaining

If your repo already uses a hook manager like husky or lefthook, run sitecmd check from inside their config rather than overwriting .git/hooks/pre-push. Example for lefthook:

# lefthook.yml
pre-push:
  commands:
    sitecmd:
      run: sitecmd check

Speed

The default sitecmd check reuses a scan less than 24 hours old. --strict always scans again, so its duration depends on the target and network. In CI, sitecmd check --strict detects any newly failing check; sitecmd scan --diff has a narrower regression exit condition, failing on new criticals. Persist the appropriate previous scan if either job should compare against an earlier run.

For the underlying flags, see CLI reference under sitecmd check.