Pipeline & Operations · master area

Pre-Commit Hooks

Format, lint, secrets scan before code enters the repo. Stage 0 of the pipeline. Never bypass — the hooks exist because what they catch is cheaper to catch here than in CI.

Owners: Tech Lead, Developer Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: The pipeline catches a different chain level at each stage — and stage 0 catches the cheapest.

Where it lives in the chain

• How We Build · Commit discipline — pre-commit is the first stage

What pre-commit catches

• Formatting — Prettier / gofmt / black runs automatically. No style debates in PRs.
• Linting — ESLint, ruff, etc. The team's agreed rules, applied at commit time.
• Type check (light) — fast type-check on changed files. Not the full project; that's stage 2.
• Secrets scan — gitleaks / trufflehog catches accidentally-committed credentials. Catches at commit time means the secret never enters git history.
• Conventional-commit lint — the commit message follows the team's convention. feat(grading): submit shortcut returns to next exam (GR-204)

How to do this

• Fast — under 5 seconds, ideally. Anything slower trains developers to bypass.
• Auto-fix when possible — formatting and import sorting fix themselves; the developer doesn't have to think.
• Never bypass — --no-verify is a smell. A failing hook is information, not friction. If the hook is wrong, fix the hook by PR; if the change is right, fix the change.
• Installed by default — pnpm install (or equivalent) sets up the hooks. Hooks that require manual setup are hooks that half the team doesn't have.

What good practice looks like

A new developer clones the repo. First commit triggers the hooks — they pass or they fix the file automatically. No "did you remember to install Husky?" conversation. The team's standards are enforced at the moment of commit, not litigated at PR review.

A team that bypasses pre-commit under deadline pressure gets the same kind of incident the JWT outage produced — a config change that bypassed the pipeline because someone thought it was too small to need it. The discipline of never bypass is not pedantry. It is the chain's first line of catches.

Related crafts

• CI/CD Pipeline — what pre-commit feeds
• Secrets Management — what the secrets-scan defends