How to contribute

The canonical contribution guide is CONTRIBUTING.md. This page summarizes the workflow and links to deeper guides for testing, debugging, and conventions.

Pickup process

1. Look for an open issue describing the change. If none exists, open one first and comment that you're working on it.
2. Link your PR to the issue. Fill out the PR template (.github/PULL_REQUEST_TEMPLATE.md).
3. Make sure tests pass. The CI matrix runs on Ubuntu and Windows with Go 1.25 (.github/workflows/test.yml).

Definition of done

A PR is ready for merge when:

• go build ./... succeeds on all platforms (Ubuntu and Windows are gated).
• go test ./... passes (CI uses gotestsum --raw-command -- go test -json ./... --race).
• For changes to rules: go generate ./... produces no diff against config/gitleaks.toml. The CI step Validate Config enforces this.
• golangci-lint run is clean (lints configured in .golangci.yaml). Locally: make lint.
• The change is reviewed by a maintainer and any feedback addressed.

Adding a new rule

This is the most common contribution. The full walk-through is in CONTRIBUTING.md, but the steps in brief:

1. Create cmd/generate/config/rules/{provider}.go defining a function that returns *config.Rule. Use GenerateSemiGenericRegex (when an identifier keyword is required) or GenerateUniqueTokenRegex (when the prefix is unique enough to stand alone). Both are defined in cmd/generate/config/utils/generate.go.
2. Provide true positive (tps) and false positive (fps) samples. The validate(r, tps, fps) helper checks them at config-generation time, so a misconfigured rule fails the make build step rather than slipping through.
3. Add rules.YourProvider(), to the configRules slice in cmd/generate/config/main.go, keeping it alphabetical.
4. Run make config/gitleaks.toml (or just make build) to regenerate the embedded default config.
5. Spot-check the new rule in the generated config/gitleaks.toml.
6. Open a PR.

The repo has 131 rule files at the moment, contributing 222 compiled rules — a single .go file often produces multiple variants (e.g., aws.go produces several AWS rule shapes).

Sub-pages

• Development workflow — branch, code, test, PR, merge cycle
• Testing — what gets tested where, how to run
• Debugging — logs, profiling, common pitfalls
• Patterns and conventions — the unwritten rules
• Tooling — Makefile, golangci-lint, goreleaser