Secret scanning with gitleaks and pre-commit

The idea

People forget; machines do not. Secret scanning uses regexes and entropy to spot strings that look like API keys, tokens or private keys. Scan in three places:

flowchart LR
  D["Dev machine<br/>pre-commit hook"] --> P["Pull request<br/>CI scan"]
  P --> R["Repo / history<br/>scheduled scan"]

Blocking on the dev machine is cheapest: the secret never leaves the laptop.

gitleaks

gitleaks is an open-source, single-binary tool with hundreds of built-in rules for AWS, GitHub, Slack, Stripe, private keys and more.

gitleaks git -v .                     # scan the repo's whole Git history
gitleaks dir -v .                     # scan current files, no Git needed
gitleaks git --report-path leaks.json --report-format json .

Older versions (before 8.19) use gitleaks detect --source . and gitleaks protect --staged; you will still see them in older docs. The exit code is non-zero when leaks are found, so CI fails.

Results include the file, line, commit, author and matching rule. Add --redact so gitleaks masks secret values in its output; turn it on in CI so you do not print the secret into the log yourself.

Blocking at commit time

The pre-commit framework runs hooks before every git commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.0
    hooks:
      - id: gitleaks

pip install pre-commit
pre-commit install            # install the hook into .git/hooks
pre-commit run --all-files    # try it on the whole repo

A local hook can be skipped with git commit --no-verify, so CI must scan again. GitHub also offers secret scanning and push protection, which block pushes containing known secret formats.

False positives

Sample values in tests or docs may be flagged by mistake. Handle them with:

• A gitleaks:allow comment at the end of the line.
• A .gitleaks.toml file with an [allowlist] by path or regex.
• A .gitleaksignore file listing fingerprints of findings confirmed safe.

Do not disable a whole rule because of one false positive. And if a finding is real, the process is rotate first, clean up later.