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. The design philosophy is that regex rules are sufficient for most secret detection.

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 `-c, --config` for the config file path, which the help text says follows an order of precedence, and `-b, --baseline-path` for a baseline of issues that can be ignored.

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 save findings to a report file with `--report-path` also makes it usable in CI pipelines.

Key Features and Configuration Options

The tool offers several features that go beyond basic scanning. A baseline lets you ignore findings you already know about: when scanning large repositories or repositories with a long history, gitleaks ignores any old findings present in the baseline, and a baseline can be any gitleaks report created with the `--report-path` parameter. That is useful for gradually remediating a large backlog of secrets without failing on every old finding. The `git` command lets you shape `git log -p` through the `log-opts` option, so you can restrict a scan to a range of commits, and the `dir` command (aliases `files` and `directory`) scans directories and individual files. The `detect` and `protect` commands deprecated in v8.19.0 are still available but hidden in the `--help` menu, and the README links a gist for translating old commands.

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. 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, 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; 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 at the repository root; consult the documentation for how that mechanism works.

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.

Frequently asked questions

Official sources

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