Gitleaks

Last reviewed Aug 26, 2026 · 813 words

Run Gitleaks against the repository before you make it public, not after. It reads the entire commit history, not just the working tree, and an API key you deleted 3 years ago in commit 40 is still one git log -p away for anyone who clones. Once a secret has reached a public remote the only fix is rotation, and the scan is the 5 seconds that tells you whether you need to. That framing matters because the tool is a scanner, not a server: a single 128 MB Go binary, MIT-licensed, that you put in three places, your shell, your commit hook and your CI.

One binary, three scanning modes

Current releases expose the modes as subcommands. gitleaks git walks commit history, gitleaks dir scans plain files with no git involved (useful for a config directory or an extracted archive), and gitleaks stdin reads a stream. Older releases called these detect and protect; the flags carry over.

gitleaks git -v --report-format sarif --report-path gitleaks.sarif

Without Go installed, the container does the same job with the repository mounted:

docker run --rm -v "$(pwd):/repo" ghcr.io/gitleaks/gitleaks:latest git -v /repo

A 10,000-commit repository finishes in seconds; a 200,000-commit monorepo takes a few minutes and most of that is git, not the matcher. The exit code is 1 when a leak is found, which is what makes it usable in CI without any wrapper script.

The hook that stops the leak before it exists

History scanning is the audit; the pre-commit hook is the prevention, and it is the part that repays the setup for years. With the pre-commit framework the whole configuration is:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.x.y   # pin to the current release tag
    hooks:
      - id: gitleaks

pre-commit install once per clone and every commit is scanned for staged secrets in well under a second. The hook is the reason I stopped worrying about .env files being one careless git add . away from a public repo, and the reason the false-positive handling below matters: a hook that cries wolf gets bypassed with --no-verify within a week.

Self-hosted CI without the licence key

The official GitHub Action needs a paid licence for organisation-owned repositories, which is a fair reason to run the scanner on your own forge instead. On a Forgejo or Gitea instance with Woodpecker the step is the container image and one command:

steps:
  - name: gitleaks
    image: ghcr.io/gitleaks/gitleaks:latest
    commands:
      - gitleaks git --no-banner -v .

Make sure the runner clones with full depth; a shallow clone of 1 commit scans 1 commit. Run it on every push and weekly on the default branch, because rules get added and last month's clean history can fail today's ruleset for good reason. The self-hosted git forge comparison covers which forge gives you Actions-compatible pipelines out of the box.

False positives: exclude precisely, never disable

Detection is regex plus entropy, and the packaged rules will flag test fixtures, example keys in documentation and the occasional long hex string. The three tools, in order of preference, are an inline comment, a fingerprint file and a path exclusion in the config.

[extend]
useDefault = true

[allowlist]
paths = ['''testdata/.*''', '''docs/examples/.*''']

Append # gitleaks:allow to a line that is a known dummy value. For a historic finding you have already rotated, copy the fingerprint from the report into .gitleaksignore so it stops reappearing without weakening the rule. Custom [[rules]] entries with your own regex catch internal token formats the defaults have never heard of. What you should not do is set the exit code to 0 to make CI green; that turns a scanner into a log line nobody reads.

Where TruffleHog fits alongside it

Gitleaks is fast and pattern-based. TruffleHog goes further and verifies findings by calling the provider to check whether a key is live, across several hundred detector types, which is slower, makes outbound requests from your CI, and produces a much more actionable list. They are not rivals: Gitleaks in the hook and on every push for speed, TruffleHog on a weekly schedule for verification. Both run happily inside the same Woodpecker pipeline.

What I'd do

Install the pre-commit hook in every repository today, add the Woodpecker step to every pipeline this week, and run a one-off gitleaks git across every repository you own, including the private ones you plan to keep private, because "private" has a way of changing. Rotate anything it finds rather than rewriting history, which never quite gets every clone. After that it costs you a sub-second delay per commit, which is the cheapest security control in your entire stack.