Gitleaks: Open-Source Secret Scanning for Git Repos in 2026

# Install gitleaks via Homebrew (macOS/Linux)
brew install gitleaks

# Or download the binary directly
# https://github.com/gitleaks/gitleaks/releases

# Verify installation
gitleaks version

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks
        name: gitleaks-protect
        entry: gitleaks protect --staged --verbose
        language: golang
        pass_filenames: false

# .github/workflows/secret-scan.yml
name: Secret Scanning

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Gitleaks
        uses: gitlea

ks/gitleaks-action@v2 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

**Rationale:** `fetch-depth: 0` is required for full history scanning. Without it, the action only sees the latest commit, defeating the purpose of historical analysis. The `GITLEAKS_LICENSE` secret is only required for private repositories when using the official action. For public repos, or when running the binary directly, the MIT license applies without restriction.

**Alternative CI (Direct Binary):**

If licensing constraints or runner compatibility are concerns, download and run the binary directly:

```yaml
- name: Download Gitleaks
  run: |
    curl -LO https://github.com/gitleaks/gitleaks/releases/download/v8.18.0/gitleaks_8.18.0_linux_x64.tar.gz
    tar -xzf gitleaks_8.18.0_linux_x64.tar.gz

- name: Run Gitleaks Detect
  run: ./gitleaks detect --source . --report-path gitleaks-report.json --report-format json

This approach remains fully MIT-licensed regardless of repository visibility.

3. Ruleset Customization

Gitleaks ships with a default ruleset, but internal services often use custom token formats. Adding a rule requires editing a TOML configuration file.

Implementation:

# gitleaks.toml
[[rules]]
id = "internal-api-key"
description = "Internal service API key (32-char hex prefix)"
regex = '''internal_key_[a-f0-9]{32}'''
entropy = 3.5
tags = ["internal", "api-key"]

[rules.allowlist]
regexes = ['''internal_key_00000000000000000000000000000000''']

Rationale: The entropy field filters low-complexity matches. A threshold of 3.5 bits per character is typical for hex strings. The allowlist section prevents false positives from documentation examples or placeholder values. Custom rules should be committed to the repository to ensure consistent scanning across all environments.

4. Historical Remediation

Running gitleaks detect on a repository with past leaks will surface findings even after key rotation. The secret remains in the git object store. Rotation mitigates active risk but does not remove the artifact.

Remediation Workflow:

1. Rotate all exposed credentials immediately.
2. Use git filter-repo or BFG Repo-Cleaner to rewrite history.
3. Force-push the cleaned branch.
4. Notify all collaborators to re-clone or reset their local copies.

Example:

# Install git-filter-repo
pip install git-filter-repo

# Rewrite history to remove a specific file containing secrets
git filter-repo --invert-paths --path secrets.env

# Force push (coordinate with team)
git push --force --all

Rationale: Git is append-only by design. Removing data requires rewriting commit hashes, which breaks downstream clones. Coordination is mandatory to prevent merge conflicts and data loss.

Pitfall Guide

1. Running detect Without fetch-depth: 0

Explanation: Shallow clones in CI only include the latest commit. Gitleaks will miss secrets buried in historical commits. Fix: Always set fetch-depth: 0 in checkout steps when using GitHub Actions or GitLab CI.

2. Relying Solely on Pre-commit Hooks

Explanation: Developers can bypass hooks with --no-verify or use clients that ignore them. Pre-commit is a convenience, not a enforcement mechanism. Fix: Implement CI scanning as the authoritative gate. Pre-commit reduces noise; CI prevents escapes.

3. Ignoring Entropy Thresholds

Explanation: Regex matches on low-entropy strings (e.g., AKIAIOSFODNN7EXAMPLE) generate false positives. Without entropy filtering, noise overwhelms signal. Fix: Configure entropy values in custom rules. Use the default ruleset's entropy checks as a baseline.

4. Assuming Rotation Removes Secrets from Git

Explanation: Rotating a key stops active abuse but leaves the credential in the repository history. Bots may have already cached the value. Fix: Combine rotation with history rewriting using git filter-repo. Treat rotation as incident response, not remediation.

5. Hardcoding Allowlists in CI

Explanation: Allowing specific patterns in CI configuration creates drift between local and remote scans. Developers may push allowed patterns locally that fail in CI. Fix: Commit the gitleaks.toml configuration to the repository. Ensure all environments use the same ruleset.

6. Overlooking SARIF Integration

Explanation: JSON reports are machine-readable but lack UI integration. Teams may miss findings if they rely on console output. Fix: Enable SARIF output and upload to GitHub Code Scanning. This surfaces findings in the PR diff and repository security tab.

7. Running protect Without --staged

Explanation: Scanning the working directory includes untracked files and build artifacts. This increases scan time and false positives. Fix: Always use --staged in pre-commit hooks. It limits scope to changes about to be committed.

Production Bundle

Action Checklist

• Install Gitleaks CLI and verify version compatibility with team tooling
• Configure .pre-commit-config.yaml with gitleaks protect --staged
• Add CI workflow with fetch-depth: 0 and SARIF report upload
• Commit gitleaks.toml with custom rules for internal token formats
• Set entropy thresholds on custom rules to filter low-complexity matches
• Document rotation and history rewriting procedures in runbooks
• Test pre-commit hook bypass resistance by verifying CI enforcement
• Review SARIF findings in GitHub Code Scanning dashboard weekly

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
< 20 developers, rare leaks	Gitleaks + pre-commit + CI	Sufficient coverage, low overhead	Free (MIT binary)
> 50 developers, frequent leaks	GitGuardian or similar	Dashboard, auto-revocation, triage reduce coordination cost	$10–$50/dev/month
Open-source project	Gitleaks direct binary	No licensing restrictions, full history scan	Free
Compliance-driven (SOC 2, HIPAA)	Commercial scanner with audit logs	Built-in reporting, centralized incident management	Higher tier pricing
Custom internal tokens	Gitleaks + custom TOML rules	Regex-based detection is deterministic and auditable	Free

Configuration Template

# gitleaks.toml
# Global settings
[config]
    # Maximum file size to scan (bytes)
    max-file-size = 1048576
    # Enable entropy checking
    entropy-check = true

# Default rules are loaded automatically.
# Add custom rules below.

[[rules]]
id = "custom-service-token"
description = "Internal service token (prefix + 40 hex chars)"
regex = '''svc_token_[a-f0-9]{40}'''
entropy = 4.0
tags = ["internal", "service-token"]

[rules.allowlist]
regexes = [
    '''svc_token_0000000000000000000000000000000000000000''',
    '''svc_token_ffffffffffffffffffffffffffffffffffffffff'''
]
paths = [
    '''docs/.*'''
]

Quick Start Guide

1. Install CLI: Run brew install gitleaks (macOS/Linux) or download the binary from GitHub releases.
2. Initialize Pre-commit: Add the Gitleaks hook to .pre-commit-config.yaml and run pre-commit install.
3. Verify Local Scan: Create a test file with a known pattern (e.g., AKIAIOSFODNN7EXAMPLE) and run gitleaks protect --staged. Confirm detection.
4. Add CI Workflow: Copy the GitHub Actions template to .github/workflows/secret-scan.yml. Ensure fetch-depth: 0 is set.
5. Commit and Push: Push changes. Verify the action runs and SARIF results appear in the repository security tab.