Pre-push hooks

A pre-push hook runs locally, on your machine, every time you git push. If you can fail a build in CI for a regression, you can also fail the push that would have caused the regression. The fix loop tightens from “push, wait for CI, fix, push again” to “the regression never leaves your laptop.”

SiteCMD ships a hook installer in the CLI.

Install

In a project that has a .sitecmd/ directory (run sitecmd init first if not):

sitecmd check --install

This writes a .git/hooks/pre-push script that calls sitecmd check on every push. Run sitecmd check --install --strict instead to have the hook call sitecmd check --strict.

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 gate on new issues instead of a score number.

What the hook checks

The default mode is a score gate: sitecmd check compares your score against the threshold (--threshold 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 nothing to compare against, so it records a baseline and passes.

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 --threshold 85

Tweak this until it’s strict enough to be useful but not so strict it’s annoying. A common pattern is to start at “current score minus 5” and tighten over time.

Skipping a push

The hook is local. If you absolutely need to push past it (you’re fixing something urgent, you know it’ll regress temporarily), git push --no-verify skips all pre-push hooks. Use sparingly; the entire point is to make regressions visible.

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

A pre-push hook should be fast. The default sitecmd check mode is the fast one: it reuses the last scan when it’s under 24 hours old, so most pushes don’t scan at all. --strict always runs a fresh scan; scans typically finish in a few seconds, but if that’s too slow for your push cadence, use the default score gate for the hook and leave strict-style regression gating to CI (sitecmd scan --diff).

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