---
id: 07-gitleaks-precommit
epic: ci-security-and-supply-chain
title: Gitleaks pre-commit hook
type: technical-story
status: done
feature: tooling
depends-on: []
blocks: [09-ci-security-guide-and-docs]
created: 2026-05-14T18:59:12+02:00
updated: 2026-05-14T19:16:52.691Z
---

## Goal

Add `gitleaks protect --staged --redact` as a step in `.husky/pre-commit` and ship a `.gitleaks.toml` allowlist that covers test-fixture patterns in `__seeds__/**`, so a commit containing a known secret pattern is blocked locally before it reaches the remote.

## Why

Developer accidents (pasting tokens into config, seeding test fixtures with real-looking keys) are the most common secret-leak vector. A pre-commit hook stops the leak at the earliest possible point — before the secret is ever pushed. GitHub native push protection is the second line of defense (documented in Story 09's guide); the hook is the first. The `__seeds__/**` allowlist prevents false positives from test fixtures that deliberately use token-shaped strings as dummy data.

## Done when

- `.husky/pre-commit` has a `gitleaks protect --staged --redact` step that runs before the existing state-sync guard (or after — order between guards doesn't matter, both must run).
- `.gitleaks.toml` exists at repo root with at minimum one allowlist rule scoping `__seeds__/**` test fixtures (using `paths` or `allowlist.paths` depending on the gitleaks version).
- A smoke test (bash script or vitest) pipes a staged commit containing a Stripe-style test key (`sk_test_...`) through the hook and asserts non-zero exit code. The smoke test is documented in the story's Done-when but may live as a manual verification step given gitleaks requires a binary; include instructions in `docs/guides/ci-security.md` (Story 09) for consumers to verify locally.
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass.

## In scope

- `.husky/pre-commit` — new `gitleaks` step.
- `.gitleaks.toml` — allowlist config.

## Out of scope

- Installing `gitleaks` as a project devDependency — consumers install it via their OS package manager or `brew`; the hook exits gracefully with a warning if `gitleaks` is not found in `$PATH` (to avoid blocking developers who haven't installed it yet, while still enforcing for those who have).
- GitHub native push protection configuration — consumer-facing instruction deferred to Story 09's guide.

## Tasks

- [x] Add `gitleaks protect --staged --redact` step to `.husky/pre-commit` (exit-gracefully if `gitleaks` not in `$PATH`); create `.gitleaks.toml` at repo root with `__seeds__/**` allowlist for test-fixture patterns; one commit, all gates pass.