agentic-dev/docs/work/ci-security-and-supply-chain/07-gitleaks-precommit/_story.md

id, epic, title, type, status, feature, depends-on, blocks, created, updated

id	epic	title	type	status	feature	depends-on	blocks	created	updated
07-gitleaks-precommit	ci-security-and-supply-chain	Gitleaks pre-commit hook	technical-story	done	tooling		09-ci-security-guide-and-docs	2026-05-14T18:59:12+02:00	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

• 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.