Skip to main content

Source: ocean/docs/adr/0009-secret-scanning-in-pre-commit-hooks.md | ✏️ Edit on GitHub

ADR-0009: Secret Scanning in Pre-Commit Hooks

Status​

Accepted

Context​

We discovered that a Stripe test API key was committed to the repository and only caught by GitHub's push protection, not our local pre-commit hooks. While GitHub's server-side scanning is excellent, we should catch secrets before they're even committed locally.

Decision​

We will add optional secret scanning to our pre-commit hooks using Gitleaks, a popular open-source secret scanner.

Implementation Details​

  1. Gitleaks Configuration (.gitleaks.toml):

    • Allow example files and test files
    • Allow documentation placeholders like sk_test_... or your_key_here
    • Scan all other files for real secrets

  2. Pre-commit Hook Enhancement:

    • Add optional Gitleaks scanning if the tool is installed
    • Developers can install it via: brew install gitleaks (macOS) or download from GitHub
    • If not installed, the hook continues without secret scanning

  3. Why Optional:

    • Doesn't force all developers to install another tool
    • GitHub push protection still acts as the final safety net
    • Developers working with sensitive data can opt-in for extra protection

Consequences​

Positive​

  • Catches secrets before they enter git history
  • Educates developers about secret hygiene
  • Complements GitHub's push protection
  • No forced dependencies on the team

Negative​

  • Slightly longer commit times when enabled
  • May have false positives that need allowlisting
  • Requires manual installation for full protection

References​