Introduction
In 2026, secret leaks in Git repositories account for 85% of security breaches according to OWASP reports, causing millions in losses per incident. Gitleaks, an open-source Go tool, scans Git history for sensitive patterns like AWS keys, JWT tokens, or SQL passwords. Unlike tools like TruffleHog that focus on entropy, Gitleaks shines with its speed (millions of commits in seconds) and custom regex configurability. This advanced tutorial guides you from installation to CI/CD integration, including custom rules and baselines for remediation. By the end, you'll automate detection in your pipelines, making your repos audit-proof for SOC2 or GDPR compliance. Perfect for DevSecOps teams managing complex monorepos.
Prerequisites
- Go 1.22+ installed (for native compilation)
- Git 2.45+ with a test repo containing simulated secrets
- Access to a GitHub repo for CI/CD
- Advanced knowledge of regex and YAML/TOML
- Unix-like terminal (WSL on Windows)
Installing Gitleaks
go install github.com/gitleaks/gitleaks/v8@latest
gitleaks version
# Verification: expected output v8.18.4 or higher
echo $?
# Static binary option for CI/CD
CGO_ENABLED=0 go install -ldflags='-s -w' github.com/gitleaks/gitleaks/v8@latestThis script installs Gitleaks via Go modules, checks the version, and builds a static binary optimized for CI environments without Go dependencies. Skip slow Go proxies by using @latest directly; the static binary shrinks size by 70% in production.
First Basic Scan
Before advanced configs, test Gitleaks on a repo with fake secrets. Create a test repo: git init test-repo && cd test-repo && echo 'AWS_KEY=AKIAIOSFODNN7EXAMPLE' > secret.txt && git add . && git commit -m "add secret".
Initial Repo Scan
cd test-repo
gitleaks detect --source . --verbose --report-format json --report-path leaks.json
cat leaks.json
git log --oneline | head -5This scan targets the current directory, generates a detailed JSON report with hex fingerprints for precise remediation. The --verbose flag shows matched rules; use --no-git for non-Git scans like S3 buckets.
Custom TOML Configuration
title = "Custom Enterprise Config 2026"
[[rules]]
id = "aws-access-key"
description = "AWS Access Key ID"
regex = '''AKIA[0-9A-Z]{16}'''
entropy = 3.5
keywords = [
"aws_access_key",
"aws_access_key_id"
]
[[rules]]
id = "jwt-token-custom"
description = "Enterprise JWT Token"
regex = '''eyJ[^\"]{100,}'''
allowlist = [
"public-jwt-example"
]
[baseline]
path = ".gitleaks-baseline.toml"
[remediation]
commit = trueThis TOML config adds a standard AWS rule and a custom one for JWTs with an allowlist for false positives. The baseline section ignores historical leaks; remediation.commit=true automates secret squashes via gitleaks protect. Prioritize entropy to cut false positives by 40%.
Scan with Custom Configuration
Tip: Place .gitleaks.toml at the repo root. For monorepos, use --config-path.
Advanced Scan with Baseline
# Generate initial baseline
gitleaks detect --baseline .gitleaks-baseline.toml --source .
# Scan with baseline (ignores existing leaks)
gitleaks detect --baseline .gitleaks-baseline.toml --source . --exit-code 1 --report-path advanced-leaks.sarif
# Pre-push protection
exit 1 # Simulate CI failureThe baseline captures the initial leak state for incremental scans without alerting on history. --exit-code 1 forces CI failure; SARIF integrates with GitHub CodeQL. Update the baseline after remediation with gitleaks detect --update.
Pre-Commit Hook with Husky
#!/bin/sh
# .husky/pre-commit
gitleaks protect --source . --verbose
# Or via pre-commit framework
# pip install pre-commit
# echo -e '[hooks]\n - id: gitleaks\n entry: gitleaks protect --staged' > .pre-commit-config.yaml
# pre-commit install
exit 0This hook blocks commits with secrets by scanning only the staging area (--staged). Integrate with Husky for Node.js or pre-commit for multi-language support; add --redact-log to mask secrets in Git logs.
GitHub Actions Integration
For CI/CD, embed Gitleaks in GitHub workflows for automated PR scans.
GitHub Actions Workflow
name: Gitleaks Scan
on: [push, pull_request]
jobs:
gitleaks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Gitleaks
run: |
curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.18.4/gitleaks_8.18.4_linux_x64.tar.gz | tar -xzf - gitleaks
sudo mv gitleaks /usr/local/bin/
gitleaks version
- name: Scan
uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
config-path: .gitleaks.toml
baseline-path: .gitleaks-baseline.toml
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: gitleaks.sarifThis workflow scans on every push/PR, uses a static release for reliability, and uploads SARIF for GitHub Security tab visualization. fetch-depth: 0 ensures full history; auto-token works for private repos.
Best Practices
- Prioritize custom rules: Always add
keywordsto contextualize regex and reduce false positives by 60%. - Baselines in production: Generate them after initial audits, version them as
.gitleaks-baseline.private.toml(gitignore). - Multi-CI integration: Use Docker image
ghcr.io/gitleaks/gitleaks:latestfor GitLab/Jenkins. - Log redaction: Enable
--redactto mask secrets in reports/Slack notifications. - Monitoring: Pipe JSON to ELK for leak dashboards by repo/team.
Common Errors to Avoid
- Missing Git history: Without
fetch-depth: 0in CI, only recent commits are scanned, missing 90% of leaks. - Overly broad regex: Without
entropyorkeywords, false positives block devs (e.g., UUIDs as API keys). - No baseline: Initial scans fail massively on legacy code; generate it systematically.
- CI permissions: Token without
security-events:writeblocks SARIF upload and PR annotations.
Next Steps
- Official docs: Gitleaks GitHub
- Community rules: awesome-gitleaks
- Advanced alternative: Integrate with GitGuardian for S3 scans.
- Training: Check out our DevSecOps training to master Trivy + Gitleaks in end-to-end pipelines.