Development workflow

The expected loop for a typical change.

1. Set up your branch

Branch off master. There are no special branch-name conventions, but most contributors use feat/, fix/, or chore/ prefixes that mirror commit messages.

2. Edit code

Most rule additions touch only cmd/generate/config/rules/<provider>.go and cmd/generate/config/main.go. Engine changes will land in detect/, config/, sources/, or report/. See systems for which package owns what.

3. Regenerate the default config (rule changes only)

If you touched anything under cmd/generate/config/, regenerate config/gitleaks.toml:

make config/gitleaks.toml
# or, equivalently:
go generate ./...

The Makefile rule depends on cmd/generate/config/**/* so this only runs when sources have changed. The CI job Validate Config runs go generate ./... and then git diff --exit-code — uncommitted differences fail the build.

4. Run tests locally

make test       # full suite with --race
# or:
make failfast   # stop on first failure for tighter inner loop

The full suite spends most of its time in detect/detect_test.go. For rule-only changes, the fast feedback comes from the validation that runs at config-generation time inside cmd/generate/config/main.go — validate(r, tps, fps) calls Detect against your sample inputs and fails fast if a true positive doesn't match or a false positive does.

5. Lint

make lint

The configuration in .golangci.yaml enables revive (severity: error), staticcheck, misspell, inamedparam, exhaustruct, nonamedreturns, and unconvert. Most other linters are explicitly disabled.

6. Commit and PR

Commit messages on this repo are loose; many older commits use [bracket] prefixes, while newer ones lean on Conventional Commits. Either is fine — the project doesn't enforce a format.

When you open the PR:

• Fill out .github/PULL_REQUEST_TEMPLATE.md.
• Link to the related issue.
• Wait for CI (.github/workflows/test.yml) — Ubuntu and Windows must both pass.
• Maintainers will review. PRs that are tied to a clear issue and pass CI usually move quickly.

7. Releases (maintainers)

Releases are cut by tagging master. The .github/workflows/release.yml workflow publishes the binary via GoReleaser (config in .goreleaser.yml). The Docker image is published separately to Docker Hub and ghcr.io/gitleaks/gitleaks.