08 — Pre-commit and hooks

What runs when you git commit here, what blocks, what doesn't, and why nothing should be bypassed.

Hook installation

One-time, per clone:

pre-commit install \
  --hook-type pre-commit \
  --hook-type pre-push \
  --hook-type post-commit

If the hooks aren't installed, the local commit will skip them — but PR review is the catch-net, and a missed scan in a feature branch can still catch the secret before merge.

Active hooks

TruffleHog (pre-commit, blocking)

Scans the staged content for high-entropy strings and known secret patterns (AWS keys, GCP service-account JSON, GitHub tokens, generic JWTs, etc.).

Blocks the commit on any positive match.
NEVER bypass with git commit --no-verify or git commit -n. This is on the don't-touch list — see ../docs/global/SANCTITY_RULES.md.
If the hook fires on a real secret: stop, rotate the credential immediately (any value that touched a Git working tree is half-burned), then move to External Secrets Operator. See ./06-secrets-and-identity.md.
If the hook fires on a false positive: fix the regex in pre-commit-scripts/ rather than skip-listing the file. The fix is reusable across the org.

CAC and Yaak (pre-commit / pre-push, gated)

These hooks exist in the platform's standard .pre-commit-config.yaml, but they are gated on file paths this repo doesn't carry (CAC config files, Yaak collections). They no-op here. The same scripts run for real in service repos.

If a future change ever introduces matching paths, the hooks will start firing — read their messages and fix forward. Do not disable.

Background hooks

Cursor AI commit metric collector (post-commit, non-blocking)

Posts a metric ping to observe.meeshogcp.in describing the commit (author, files touched, AI tool used). Runs in the background, does not block, and silently drops on failure.

This is the only sanctioned outbound call to a *.meeshogcp.in host the agent should ever observe in this repo. Agents must still refuse to initiate any such call themselves. See ../docs/global/SANCTITY_RULES.md.
If the post-commit script is failing, that's a platform issue — escalate per ../docs/global/escalation-matrix.md. Do not remove the script.

Why never `--no-verify`

A bypassed pre-commit hook is invisible to the PR reviewer. Real secrets ship through merged PRs are very expensive to recover from:

The credential itself must be rotated everywhere it's used.
The Git history must be force-rewritten (and even then, the Git push may be cached on a mirror).
Any system that ingested the secret value (CI logs, Slack quotes, downstream forks) is now compromised.

The 5 seconds saved bypassing the hook is a 5-day-or-more incident later.

When the hook is wrong

Two kinds of false-positive:

Pattern over-matches — TruffleHog regex matches a non-secret high-entropy string (a hash, a UUID, a build label). Fix: tighten the regex in pre-commit-scripts/.
Genuine fixture / test data — a fake-looking string in a chart's example values or test fixture. Fix: same — tighten the pattern, or move the fixture to a path TruffleHog already excludes (chart templates/ test fixtures usually qualify).

Either way, the fix is in the hook, not in the bypass.

3.7 KiB Raw Blame History