Gitleaks Deployment and Usage Guide

Prerequisites

Git (2.0+): Required for repository scanning
Go (1.20+): Only needed if building from source
Docker (optional): For containerized deployments
Homebrew (macOS/Linux only): For package manager installation

Installation

Option 1: Homebrew (macOS/Linux)

brew install gitleaks

Option 2: Docker

# Docker Hub
docker pull zricethezav/gitleaks:latest

# GitHub Container Registry
docker pull ghcr.io/gitleaks/gitleaks:latest

Option 3: Build from Source

git clone https://github.com/gitleaks/gitleaks.git
cd gitleaks
make build

The binary will be available at ./gitleaks.

Option 4: Binary Download

Download pre-built binaries for your platform from the releases page.

Configuration

Configuration File Precedence

Gitleaks uses the following order of precedence for configuration (first match wins):

Command line: --config or -c flag
Environment variable: GITLEAKS_CONFIG (path to file)
Environment variable: GITLEAKS_CONFIG_TOML (raw TOML content)
Local config: .gitleaks.toml in the target scan path

Basic Configuration File

Create .gitleaks.toml in your repository root:

title = "Gitleaks Config"

[extend]
# Use default rules plus custom
useDefault = true

[[rules]]
id = "custom-api-key"
description = "Custom API Key"
regex = '''(?i)(api_key|apikey)(.{0,20})?['\"][0-9a-zA-Z]{16,45}['\"]'''
tags = ["api", "key"]

[rules.allowlist]
paths = [
    '''vendor\/''',
    '''\.env\.example$'''
]
regexes = [
    '''example-key-[0-9a-f]{8}'''
]

Environment Variables

# Set config path
export GITLEAKS_CONFIG=/path/to/config.toml

# Or embed config directly
export GITLEAKS_CONFIG_TOML="[extend]\nuseDefault = true"

# For GitHub Actions (Organizations only)
export GITLEAKS_LICENSE=your_license_key

Baseline (Ignoring Known Issues)

Generate a baseline to ignore existing secrets:

gitleaks git --baseline-path gitleaks-baseline.json .

Build & Run

Local Development Build

make build
./gitleaks version

Scanning Commands

Git Repository Scan (full history):

gitleaks git -v .

Git Repository Scan (last commit only):

gitleaks git --no-git -v .

Directory/File Scan:

gitleaks dir /path/to/code -v

Stdin Scan:

cat file.txt | gitleaks stdin
# or
echo "api_key=abc123" | gitleaks stdin

Common Flags

-v, --verbose: Show verbose output
-c, --config: Specify config file
-b, --baseline-path: Path to baseline file
-r, --report-path: Output report path (use - for stdout)
-f, --report-format: json, csv, sarif, junit (default: json)
--exit-code: Exit code when leaks found (default: 1)
--redact: Redact secrets in output
--max-target-megabytes: Skip files larger than threshold
--timeout: Maximum scan duration in seconds

Example with Full Options

gitleaks git \
  --config .gitleaks.toml \
  --baseline-path baseline.json \
  --report-path findings.json \
  --report-format json \
  --redact \
  -v .

Deployment

GitHub Actions

Create .github/workflows/gitleaks.yml:

name: gitleaks
on: [pull_request, push, workflow_dispatch]
jobs:
  scan:
    name: gitleaks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}  # Required for Organizations

Pre-Commit Hook

Install pre-commit, then create .pre-commit-config.yaml:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks

Install the hook:

pre-commit install
pre-commit autoupdate

Skip on specific commits if needed:

SKIP=gitleaks git commit -m "emergency commit"

Docker in CI/CD

docker run -v $(pwd):/path zricethezav/gitleaks:latest \
  dir --verbose /path

Systemd Timer (Periodic Scans)

Create /etc/systemd/system/gitleaks-scan.service:

[Unit]
Description=Gitleaks Scan

[Service]
Type=oneshot
WorkingDirectory=/opt/repos
ExecStart=/usr/local/bin/gitleaks git --report-path /var/log/gitleaks.json .

Create /etc/systemd/system/gitleaks-scan.timer:

[Unit]
Description=Run Gitleaks daily

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Enable:

systemctl daemon-reload
systemctl enable --now gitleaks-scan.timer

Troubleshooting

False Positives

Add gitleaks:allow comment to lines that are false positives:

api_key = "test-key-12345"  # gitleaks:allow

Or use the baseline feature to ignore existing issues:

gitleaks git --baseline-path baseline.json .

Performance Issues

Large files: Use --max-target-megabytes 50 to skip large files
Slow scans: Use --timeout 300 to limit scan duration
Memory usage: Reduce --max-decode-depth for archive scanning

Configuration Not Loading

Verify precedence:

Check if --config flag is set
Check GITLEAKS_CONFIG environment variable
Check if .gitleaks.toml exists in target directory (not current working directory unless scanning .)

Docker Permission Issues

Ensure proper volume mounting:

docker run -v $(pwd):/code -w /code zricethezav/gitleaks:latest dir -v .

Exit Code 1 on Findings

This is expected behavior. To prevent pipeline failures while still reporting:

gitleaks dir . --exit-code 0

GitHub Action License Errors

Organizations require a license key. Personal accounts can use the action without GITLEAKS_LICENSE.

How to Deploy & Use gitleaks/gitleaks