Gitleaks: A Feature-Complete Secret Scanner That Is Now in Maintenance Mode

What Gitleaks Solves and Who It Is For

Gitleaks is a command-line tool that detects secrets such as passwords, API keys, and tokens in git repositories, files, and data piped through stdin. The problem it addresses is the accidental commit of credentials into source control, which can lead to account compromise and data breaches. It is aimed at developers, security engineers, and DevOps teams who want to prevent secrets from being pushed to remote repositories or who need to audit existing git history for leaked credentials. The tool is written in Go and distributed as a single binary, which makes it easy to integrate into various workflows. The README shows it works as a standalone scanner, a pre-commit hook, or a GitHub Action via the separate Gitleaks-Action repository. It is not a runtime secret manager or a network monitoring tool; it is strictly a detection utility for code and text.

The Detection Engine: Regex and Entropy

The core mechanism relies on regular expressions and entropy analysis, as explained in the linked blog post titled "Regex is (almost) all you need." The tool scans text for patterns that match known secret formats, such as the Sidekiq secret rule shown in the example output. For each finding, it reports the rule ID, the secret value, the entropy score, the file path, the line number, the commit hash, and the author. The entropy value indicates how random the string is, which helps distinguish high-entropy secrets from normal words. The fingerprint field provides a unique identifier for each finding, which is useful for tracking and for the baseline feature. The design philosophy is that regex rules are sufficient for most secret detection, though the README does not detail how it handles false positives or how it avoids re-scanning the same secret across multiple commits. The detection engine is not AI-based, despite the repository topics mentioning AI-powered; the README does not describe any LLM integration, so that topic may refer to a future direction or a separate effort.

Installation and Basic Usage

Getting started is straightforward. On macOS you can run `brew install gitleaks`. For Docker, you can pull from Docker Hub or ghcr.io and mount a host folder to scan: `docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] [OPTIONS] [SOURCE_PATH]`. You can also build from source with `git clone`, `cd gitleaks`, and `make build`. The command structure has four main subcommands: `dir` to scan directories or files, `git` to scan git repositories, `stdin` to read from standard input, and `version` to print the version. Global flags include `--config` to specify a custom config file, with a clear precedence order: the `-c` flag, the `GITLEAKS_CONFIG` environment variable, the `GITLEAKS_CONFIG_TOML` environment variable with file content, and finally a `.gitleaks.toml` file in the target path. If none are present, it uses a default config. Other useful flags are `--baseline-path` to ignore previously known issues, `--exit-code` to set the exit code when leaks are found (default 1), and `--redact` to obscure secrets in output. The `--enable-rule` flag lets you enable only specific rules by ID, which is helpful for tuning scans.

Integration with Pre-Commit and CI

For local protection, Gitleaks can be set up as a pre-commit hook. The README gives a sample `.pre-commit-config.yaml` that points to the gitleaks repository at a specific revision, `v8.24.2`, and uses the `gitleaks` hook ID. You can also use the `gitleaks-docker` hook ID to run via Docker. After creating the file, you run `pre-commit autoupdate` to get the latest version, then `pre-commit install` to activate the hook. When a commit contains a secret, the hook fails with a message like "Detect hardcoded secrets...Failed." You can bypass it with `SKIP=gitleaks git commit`, which is useful for legitimate commits that trigger false positives. For CI, the separate Gitleaks-Action repository provides a GitHub Action, but the README does not go into details about its configuration. The ability to output reports in JSON, CSV, JUnit, SARIF, or a custom template makes it suitable for integrating with CI dashboards and alerting systems.

Key Features and Configuration Options

The tool offers several features that go beyond basic scanning. The `--baseline-path` flag allows you to provide a file containing previously detected issues that should be ignored, which is useful for gradually remediating a large backlog of secrets without failing CI on every commit. The `--max-archive-depth` flag enables scanning into nested archives, but by default it is set to 0, meaning no archive traversal is done. Similarly, `--max-decode-depth` controls recursive decoding of encoded content, also defaulting to 0. These defaults are conservative to avoid performance hits, but they mean that secrets inside compressed files or base64-encoded blobs will not be found unless you explicitly enable those depths. The `--max-target-megabytes` flag skips files larger than a specified size. The `--redact` flag can obscure secrets in logs and stdout, with a percent value from 0 to 100 to partially redact. The `--diagnostics` flag enables CPU and memory profiling, which is helpful for debugging performance issues in large repositories. These options show that Gitleaks is designed for real-world constraints, but they also imply that you need to tune them to get full coverage.

Limitations and When It Is the Wrong Tool

The most significant limitation is that Gitleaks is now in maintenance mode. The README contains a warning: "Gitleaks is feature complete. I'm not merging new features into Gitleaks. Future releases will be security patches only." This means that if you encounter a secret pattern that is not covered by the existing rules, you cannot expect the project to add it. You can write custom rules in a TOML config, but that requires effort and domain knowledge. Also, the default scan does not traverse archives or decode encoded content unless you explicitly increase the `--max-archive-depth` and `--max-decode-depth` flags, so secrets hidden in those forms will be missed. The tool is not a substitute for a full data loss prevention solution; it only scans git repos, files, and stdin, not other data sources like databases or cloud storage. If your team needs an actively developed tool with new features, or if you require AI-powered detection that the repository topics hint at but do not implement, Gitleaks might not be the right choice.

Alternatives and the Successor Project

The README explicitly points to Betterleaks as the successor project, where the maintainer is shifting focus. Betterleaks is hosted at github.com/betterleaks/betterleaks, but the README does not describe its features or approach. That is a direct alternative, but without further material, you would need to inspect that repository to compare. Another common alternative is TruffleHog, which also scans git history for secrets, but it uses a different approach that includes entropy and regex as well as a broader set of detectors. The key difference is that TruffleHog is actively developed and may offer more frequent updates, whereas Gitleaks is frozen. If you need a tool that keeps pace with new secret formats, you might prefer TruffleHog or Betterleaks. However, if you value stability and a well-documented rule set, Gitleaks remains a viable option because its existing rules are comprehensive enough for many use cases.

Maintenance and Upgrade Cost

Since Gitleaks is in maintenance mode, the upgrade cost is low in terms of new features, but you should still track security patches. The latest release mentioned is v8.30.1 from March 2026, which suggests active patch releases. The project has a test CI workflow, as indicated by the badge, which gives some confidence in stability. The license is MIT, which is permissive and allows commercial use, modification, and redistribution with attribution. You do not need to worry about licensing fees or copyleft obligations. The main cost is that you cannot request new rules or features, so you may need to maintain your own custom rules in a separate config file. Also, if you rely on the pre-commit hook, you need to periodically update the revision in your `.pre-commit-config.yaml` to get security fixes, which is a simple but manual step. There is also a `.gitleaksignore` file mechanism, but the README only mentions the `--gitleaks-ignore-path` flag, not its format, so you would need to consult the documentation for that.

Editorial conclusion

Adopt Gitleaks if you need a reliable, battle-tested secret scanner that you can run in CI or as a pre-commit hook, and if you are comfortable with the fact that no new features will be added. Do not adopt it if you expect ongoing development or need features that are not already present. Before committing to it, verify that your secret patterns are covered by the default rules or that you can write custom rules, and check the current release notes for any known issues. Also, note the maintainer's pointer to Betterleaks as the successor project, so evaluate that if you want an actively developed alternative. Gitleaks remains a solid choice for scanning git history, but its roadmap is closed.

Official sources

1. gitleaks/gitleaks on GitHub
2. License: MIT
3. Project website
4. README
5. Releases