Compliance improvements with Git Hooks.

[thorwolpert]

Select Release Product

General Architecture / Framework

Summary

Adopt Lefthook as the standard git hook manager across our monorepos to enforce automated pre-commit checks (such as secret scanning with Gitleaks, code linting, and type checking) uniformly across all local development environments.

Basic Example

1. Repository Setup
   Install dependencies at the root of the workspace and register the hooks automatically via prepare:

// package.json
{
  "scripts": {
    "prepare": "lefthook install"
  },
  "devDependencies": {
    "gitleaks-secret-scanner": "^1.0.0",
    "lefthook": "^1.6.0",
    "lint-staged": "^15.0.0"
  }
}

2. Root Configuration (lefthook.yml)

# lefthook.yml
pre-commit:
  parallel: true
  commands:
    # Global Secret Scanning (All files)
    secret-scan:
      tags: security
      run: pnpm exec gitleaks-secret-scanner --staged --verbose

    # Scoped Frontend Checks (Nuxt / Vue / TS)
    frontend-lint:
      glob: "*.{js,ts,vue,json}"
      exclude: "(node_modules|\\.nuxt|\\.output)"
      run: pnpm exec lint-staged

    # Scoped Go Checks
    go-lint:
      glob: "*.go"
      run: golangci-lint run {staged_files}

    # Scoped Python Checks
    python-format:
      glob: "*.py"
      run: ruff check --fix {staged_files}

Motivation

As our codebase grows into multi-language monorepos (encompassing Nuxt/Vue/TypeScript frontends alongside Python and Golang services), maintaining local code quality and security standards has become fragmented:

1. Security Risk (Secrets in Git): Without automated pre-commit scanning, sensitive credentials or local .env values risk being accidentally committed before CI runs.
2. Inconsistent Local Developer Experience: Developers manually manage local hooks, leading to drift between team members or reliance on CI pipelines to catch trivial linting/formatting errors.
3. Heavy Orchestration Overhead: Traditional task orchestration frameworks (like Nx, Turbo, or heavy custom scripts) introduce significant setup overhead, slow execution loops, and complex configuration abstractions when all we need is fast, localized hook execution on staged files.

By adopting Lefthook, we solve these constraints with a lightweight, fast, and language-agnostic runner that operates consistently across macOS, Linux, and Windows without forcing heavy tooling onto the team.

Detailed Design

Lefthook is a Go-based, compiled binary wrapper for Git hooks. It will be installed as a root devDependency via pnpm (or native binary where applicable) and initialized automatically when a developer runs pnpm install via the prepare lifecycle script.

Key Mechanics:

1. Parallel Execution: Unlike traditional shell scripts or Husky which execute hooks serially, Lefthook executes independent pre-commit commands in parallel. A Gitleaks scan and an ESLint run execute concurrently, keeping pre-commit execution times under ~2 seconds.
2. Path & Glob Filtering: Commands are scoped using native glob rules. If a commit only touches Python files (.py), frontend linters (.vue, .ts) and Go linters (.go) are skipped entirely.
3. Automated Secret Scanning via Gitleaks: By coupling Lefthook with gitleaks-secret-scanner, Gitleaks checks staged contents in memory prior to finalizing the commit object. A shared gitleaks.toml at the root ensures consistent allowlists across the team.
4. Integration with lint-staged: For JavaScript/TypeScript packages, Lefthook delegates file filtering to lint-staged to perform auto-fixes (eslint --fix) only on staged files before they enter the index.

Requirements List

Must Have:

• Zero-Manual-Setup Onboarding: Running pnpm install must automatically install and configure git hooks for any incoming developer.
• Pre-Commit Secret Scanning: Mandatory pre-commit blocking if unencrypted API keys, private keys, or credentials are detected in staged files.
• Targeted Execution: Hook execution must be scoped via glob patterns so developers working on one service/language aren't delayed by unneeded checks for another.
• Cross-Platform Compatibility: Must run identically across macOS, Linux, and Windows environments without requiring system-level Go or global CLI installations.

Should Have:

• Fast Developer Feedback Loop: Total execution time for standard pre-commit hooks should execute in parallel and complete in under 3 seconds on standard change-sets.
• Shared Allowlist Config: A centralized gitleaks.toml at repo root to manage false positives across the team.

Could Have:

• Commit-Msg Linting: Enforcing Conventional Commit message formats (feat:, fix:, chore:) at the pre-commit-msg hook stage.

Won't Have:

• Monorepo Build Orchestration: Replacing primary build or test workflows (e.g., replacement for package scripts, Docker builds, or CI workflows). Lefthook will strictly manage local git lifecycle hooks.

Drawbacks

• Bypass Risk: Developers can still technically bypass local hooks using git commit --no-verify. (This is a fundamental trait of Git hooks; secondary CI scans must remain in place as a safety net).

• Dependency on Node Ecosystem for Bootstrap: While Lefthook itself is a Go binary, bootstrapping it via pnpm assumes a Node-capable environment at the root of the repository.

Alternatives

• Husky + lint-staged:

  • Pros: Highly ubiquitous in JavaScript/TypeScript ecosystems.
  • Cons: Executes tasks serially, requires extra wrapping/Node execution overhead for non-JS binaries like Go or Python linters, and feels clumsy in polyglot monorepos.

• Over-Engineered Monorepo Task Runners (e.g., Nx / Turborepo / Heavy CLI Task Managers):

  • Pros: Powerful caching and dependency graph awareness.
  • Cons: Too heavy and complex for basic pre-commit hygiene. Adds unnecessary mental overhead and configuration complexity when the primary requirement is simply running fast checks on staged files.

• Manual OS-Level Binaries (Homebrew / System gitleaks):

  • Cons: Causes environment drift ("works on my machine"), breaks for engineers on different OS distributions, and increases onboarding friction.

Adoption Strategy

1. Pilot Phase: Implement lefthook.yml and gitleaks-secret-scanner in a single monorepo (e.g., General Architecture / Framework or Developer Site).
2. Team Rollout: Add "prepare": "lefthook install" to root package.json. Existing team members will automatically receive the hook setup on their next pnpm install or git pull.
3. Migration Template: Provide a boilerplate lefthook.yml and gitleaks.toml in repository templates so new services adopt the pattern out of the box.
4. Non-Breaking Change: This change does not affect application runtime, deployment artifacts, or production APIs.

Unresolved Questions

• Should we mandate pre-commit hook installation in non-Node/pure-Python/Go repositories, or standardize on pnpm as the workspace bootstrapping tool across all monorepos?