Notes

Pre-commit hooks: fast local checks before CI

Pre-commit hooks catch formatting, lint, and secret issues before code leaves a laptop, but only if they stay fast and consistent.

til 2 min read
Infrastructure

CI is a great safety net, but it is still a bottleneck.

Pre-commit hooks shift quality left by running the fastest checks at the moment of change, when context is highest and fixes are cheapest.

Why hooks work

Hooks create immediate feedback loops. If a file is improperly formatted or contains a leaked secret, the developer sees it before the code leaves their machine.

That prevents noisy CI failures and reduces back-and-forth in reviews.

The key is consistency: hooks should mirror the same rules your CI uses, not a different set of standards.

What belongs in a hook

Keep hooks small and fast. A good rule of thumb is to finish in under 10 seconds for an average commit.

Effective candidates include:

  • Formatting (for deterministic diffs).
  • Linting with quick rules.
  • Secret scanning for obvious tokens.
  • Static checks that do not require network access.

Save integration tests and slow checks for CI.

Minimal example

A simple configuration can cover 80 percent of the value:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: end-of-file-fixer
      - id: trailing-whitespace
  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black

Use pinned versions so that every developer runs the same tools.

Common failure modes

  • Slow hooks. People will skip them if they slow down every commit.
  • Different rules in CI. Inconsistency erodes trust in the tooling.
  • Optional enforcement. If hooks are optional, the repo loses the safety net.

A good pattern is to use pre-commit locally and re-run the same checks in CI.

That makes local results authoritative.