Ein versehentlich eingecheckter API-Key bleibt in der Git-History, auch wenn er im nächsten Commit gelöscht wird. Gitleaks ist ein quelloffenes SAST-Werkzeug (Static Application Security Testing), das Git-Historien, Branches und Verzeichnisse mit Regex-Regeln und Entropie-Analyse nach Secrets durchsucht: API-Keys, Passwörter, private Schlüssel, OAuth-Tokens. Das Projekt hat rund 29.500 GitHub-Stars, das Docker-Hub-Image über 30 Millionen Pulls. Diese Anleitung richtet Gitleaks per Docker Compose ein, auf einem Linux-Host, einer VM oder einem NAS mit Docker, und zeigt Scans auf Abruf, Reports und die Einbindung in CI/CD.

Voraussetzungen

Docker Engine 20.10+ und Docker Compose Plugin v2 (docker compose, nicht das alte docker-compose), Installation siehe Docker und Docker Compose auf Linux installieren.
Linux-Host, VM, NAS oder WSL2 mit amd64 oder arm64 (laut Image-Manifest v8.30.1). 1 CPU-Kern und 512 MB RAM genügen, ein Scan dauert in der Regel unter einer Sekunde.
Ein lokal ausgechecktes Git-Repository mit vollständiger History (.git-Verzeichnis muss im Mount-Root liegen).
Ausgabeverzeichnis ./reports/ auf dem Host. Fehlt es, legt Docker es beim Start als root an.
Keine Datenbank, kein API-Key, kein offener Port, Gitleaks ist zustandslos.

Schritt 1: Eckdaten und Projektordner

Die wichtigsten Parameter:

Parameter	Wert
Image (empfohlen)	`ghcr.io/gitleaks/gitleaks:v8.30.1`
Alternatives Image	`zricethezav/gitleaks:v8.30.1` (Docker Hub)
Aktueller stabiler Tag	`v8.30.1` (Release März 2026, aktuell im Oktober 2026)
Image-Größe	ca. 25 MB
Exponierter Port	keiner, Kommandozeilenwerkzeug
Datenbank	keine
Report-Formate	JSON, CSV, JUnit, SARIF, Go-Template
Exit-Code bei Leaks	1 (überschreibbar mit `--exit-code=0`)
Exit-Code kein Fund	0

Legen Sie Projektordner und Report-Verzeichnis an:

$ mkdir -p ~/gitleaks/reports
$ cd ~/gitleaks

ls -la ~/gitleaks/ zeigt das Verzeichnis reports/ mit Ihrem Benutzer als Besitzer.

Schritt 2: .env-Datei anlegen

Variable Pfade und Einstellungen stehen in der .env. So bleibt die compose.yaml unverändert, wenn Sie ein anderes Repository scannen.

# Pfad zum zu scannenden Git-Repository (muss .git-Verzeichnis enthalten)
REPO_PATH=/home/user/mein-projekt

# Ausgabeverzeichnis für Reports (muss auf dem Host existieren)
REPORT_PATH=./reports

# Pfad zur optionalen Konfigurationsdatei (eigene Regeln, Allowlists)
# Datei muss existieren, wenn der Mount aktiv ist!
# Für die eingebauten Regeln Mount und GITLEAKS_CONFIG entfernen (Schritt 3).
CONFIG_PATH=./.gitleaks.toml

# Report-Format: json | csv | junit | sarif | template
REPORT_FORMAT=json

Setzen Sie REPO_PATH auf den Repository-Root, also das Verzeichnis mit dem .git-Ordner, nicht auf ein Unterverzeichnis.

cat ~/gitleaks/.env zeigt die Variablen, ls /home/user/mein-projekt/.git listet den Inhalt des .git-Ordners.

Schritt 3: compose.yaml anlegen

Gitleaks ist ein Kommandozeilenwerkzeug, kein Dienst. Die Compose-Datei nutzt deshalb restart: "no" und ein Profil: Sie starten den Scan bewusst per docker compose run.

services:
  gitleaks:
    image: ghcr.io/gitleaks/gitleaks:v8.30.1
    container_name: gitleaks-scanner
    restart: "no"
    volumes:
      - ${REPO_PATH:-./repo}:/repo:ro
      - ${REPORT_PATH:-./reports}:/reports
      - ${CONFIG_PATH:-./.gitleaks.toml}:/gitleaks.toml:ro
    environment:
      - GITLEAKS_CONFIG=/gitleaks.toml
    command: >
      git /repo
      --report-format=${REPORT_FORMAT:-json}
      --report-path=/reports/gitleaks-report.${REPORT_FORMAT:-json}
      --verbose
      --exit-code=0
    profiles:
      - scan

Hinweise:

git /repo statt detect --source: Seit v8.19.0 sind detect und protect veraltet und durch git (Repositories) und directory (Verzeichnisse ohne Git, laut README Alias von files) ersetzt. Der Pfad folgt dem Unterbefehl direkt. Mit git --source=/repo bricht v8.30.1 mit Error: unknown flag: --source ab, es entsteht dann kein Report. detect --source=/repo funktioniert noch.
:ro beim Repo-Mount: Gitleaks liest das Repository nur.
--exit-code=0: Standardmäßig endet Gitleaks bei Findings mit Code 1 und bricht so Pipelines ab. Für reine Audits ist 0 sinnvoll.
Ohne eigene Konfiguration: Entfernen Sie den dritten Volume-Eintrag und GITLEAKS_CONFIG, dann gelten die eingebauten Regeln.

docker compose config gibt die aufgelöste Konfiguration ohne Fehler aus. Warnt Docker vor fehlenden Variablen, liegt die .env nicht neben der compose.yaml.

Schritt 4: Optionale Gitleaks-Konfigurationsdatei anlegen

Mit CONFIG_PATH=./.gitleaks.toml muss die Datei vor dem Start existieren. Fehlt sie, legt Docker an ihrer Stelle ein leeres Verzeichnis an, und Gitleaks bricht ab (siehe Typische Fehler). Eine minimale .gitleaks.toml:

# .gitleaks.toml, Minimalkonfiguration

title = "Eigene Gitleaks-Konfiguration"

[extend]
# Standardregeln von Gitleaks einbinden
useDefault = true

# Beispiel: Bekanntes False-Positive-Muster ignorieren
[[allowlists]]
description = "Lokaler Testschlüssel"
regexes = ['''test_secret_[a-z0-9]{8}''']

Für den Einstieg reichen die Zeilen [extend] und useDefault = true. Eigene Regeln ergänzen Sie als [[rules]]-Blöcke. Seit v8.25.0 heißt der Abschnitt für Ausnahmen [[allowlists]] mit einer Liste regexes. Die ältere Schreibweise [[allowlist.regexes]] lehnt v8.30.1 mit Failed to load config ab.

ls -la ~/gitleaks/.gitleaks.toml zeigt eine Datei (kein Verzeichnis).

Schritt 5: Ersten Scan ausführen

Weil der Service in einem Profil liegt, starten Sie ihn mit docker compose run statt docker compose up:

$ docker compose run --rm gitleaks

Gitleaks scannt das Repository und schreibt den Report nach ./reports/gitleaks-report.json. Bei einem absichtlich eingecheckten GitHub-Token sieht die Ausgabe so aus (gekürzt):

    ○
    │╲
    │ ○
    ○ ░
    ░    gitleaks

Finding:     GITHUB_TOKEN = "ghp_tU...J9SW
Secret:      ghp_tU...J9SW
RuleID:      github-pat
Entropy:     4.903056
File:        config.py
Line:        1
Commit:      70895cff11327dab437f560d12927532e4f67787
Author:      Test
Fingerprint: 70895cff11327dab437f560d12927532e4f67787:config.py:github-pat:1

11:44PM INF 2 commits scanned.
11:44PM INF scanned ~73 bytes (73 bytes) in 52.2ms
11:44PM WRN leaks found: 1

Die Ausgabe endet mit INF … commits scanned. und WRN leaks found: N oder INF no leaks found. Steht dort 0 commits scanned, zeigt der Mount nicht auf ein Git-Repository.
ls -lh ~/gitleaks/reports/ zeigt die Report-Datei. Sie gehört root, weil der Container als root läuft.
head -50 ~/gitleaks/reports/gitleaks-report.json zeigt die ersten Findings.

Schritt 6: Report auswerten und Findings verwalten

Der JSON-Report enthält je Fund Datei, Zeile, Commit, Autor, Datum und einen eindeutigen Fingerprint der Form Commit:Datei:Regel:Zeile. Drei Wege, mit Findings umzugehen:

Option A: Inline-Ausnahme im Code

Ist ein Secret bewusst gesetzt (z. B. ein Testtoken in einer Unit-Test-Datei), schreiben Sie den Kommentar hinter die Zeile:

TEST_API_KEY = "test_secret_abc12345"  #gitleaks:allow

Option B: .gitleaksignore-Datei

Für bekannte Findings in der Git-History, die sich nicht mehr entfernen lassen, tragen Sie den Fingerprint in eine .gitleaksignore ein:

# .gitleaksignore, bekannte und akzeptierte Findings
70895cff11327dab437f560d12927532e4f67787:config.py:github-pat:1

Die Datei liegt im Repository-Root. Gitleaks findet sie dort ohne weitere Option, der Scan meldet danach no leaks found.

Option C: Baseline-Workflow

Für ältere Repositories mit vielen historischen Findings speichern Sie zuerst einen vollständigen Scan als Baseline und lassen danach nur neue Findings melden:

# Baseline erstellen
docker compose run --rm gitleaks git /repo \
  --report-format=json \
  --report-path=/reports/baseline.json \
  --exit-code=0

# Nur neue Findings (ab jetzt) melden
docker compose run --rm gitleaks git /repo \
  --baseline-path=/reports/baseline.json \
  --report-format=json \
  --report-path=/reports/new-findings.json

ls -lh ~/gitleaks/reports/ zeigt baseline.json und new-findings.json. Ohne neue Secrets meldet der zweite Lauf no leaks found, und new-findings.json enthält [].

Schritt 7: Image aktualisieren

Gitleaks erhält weiterhin Sicherheitsupdates. Tragen Sie den neuen Tag in die compose.yaml ein und laden Sie das Image. Weil der Service in einem Profil liegt, braucht pull die Option --profile scan, ohne sie lädt docker compose pull nichts. Mehr zu Container-Updates: Docker-Container automatisch aktualisieren nach dem Watchtower-Aus.

$ docker compose --profile scan pull
$ docker compose run --rm gitleaks --version

Die Ausgabe zeigt die erwartete Version, zum Beispiel gitleaks version v8.30.1.

Bonus: CI/CD-Integration

Als Pipeline-Schritt prüft Gitleaks jeden Push, bevor Code in den Hauptbranch gelangt. Secrets gehören dabei in einen Secrets-Manager, nicht in Konfigurationsdateien (siehe Docker Compose absichern).

GitHub Actions

name: Secret Scan
on: [push, pull_request]
jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0          # vollständige History, kein Shallow Clone
      - uses: gitleaks/gitleaks-action@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}  # nur für Organisationen

GitLab CI

gitleaks:
  image:
    name: ghcr.io/gitleaks/gitleaks:v8.30.1
    entrypoint: [""]
  variables:
    GIT_DEPTH: 0                  # vollständige History
  script:
    - gitleaks git . --report-path=gitleaks-report.json --exit-code=1
  artifacts:
    reports:
      sast: gitleaks-report.json
    when: always

In beiden Fällen gilt: vollständige Git-History auschecken (fetch-depth: 0 bzw. GIT_DEPTH: 0), sonst sieht Gitleaks nur den letzten Commit. gitleaks-action@v2 läuft laut Projekt-README seit 16.09.2026 nicht mehr auf GitHub-gehosteten Runnern (Node 20 entfernt), nutzen Sie @v3. Für Repositories einer GitHub-Organisation verlangt die Action zusätzlich eine kostenlose Lizenz in GITLEAKS_LICENSE.

Troubleshooting / Typische Fehler

„0 commits scanned“ und „no leaks found“ trotz vorhandener History: Der Mount zeigt nicht auf den Repository-Root. Gitleaks meldet dann fatal: not a git repository als Fehlerzeile, endet aber mit Exit-Code 0. Setzen Sie REPO_PATH auf das Verzeichnis, das .git/ direkt enthält, z. B. /home/user/mein-projekt statt /home/user/mein-projekt/src.
„dubious ownership“: Git verweigert seit 2.35.2 Repositories eines anderen Besitzers. Im offiziellen Image ist safe.directory = * bereits gesetzt, der Fehler tritt dort nicht auf. Bei eigenen Images hilft git config --global --add safe.directory /repo.
Nur ein Commit gescannt: Das Repository ist ein Shallow Clone. In GitHub Actions fetch-depth: 0, in GitLab CI GIT_DEPTH: 0 setzen.
Container startet ständig neu: In der compose.yaml steht restart: always. Nutzen Sie restart: "no" und profiles: [scan].
Report-Datei fehlt nach dem Scan: Meist ist der Aufruf fehlgeschlagen, etwa mit Error: unknown flag: --source (siehe Schritt 3). Prüfen Sie die Ausgabe auf Fehlerzeilen.
„unable to load gitleaks config, err: read /gitleaks.toml: is a directory“: Die Datei aus CONFIG_PATH fehlte beim Start, Docker hat stattdessen ein Verzeichnis angelegt (in der Regel root-eigen). Löschen Sie es mit sudo rmdir, legen Sie die .gitleaks.toml an oder entfernen Sie Mount und GITLEAKS_CONFIG.
„Failed to load config … AllowList.Regexes[0]“: Die Konfiguration nutzt die alte Allowlist-Syntax. Stellen Sie auf [[allowlists]] mit regexes = [...] um (siehe Schritt 4).
Langer Scan oder Speichermangel bei großer History: --max-target-megabytes und --timeout nutzen oder den Bereich mit --log-opts 'HEAD~50..HEAD' eingrenzen.

Häufige Fragen

Brauche ich eine Datenbank oder weitere Container?

Nein. Gitleaks läuft als einzelner zustandsloser Container ohne externe Abhängigkeiten und passt damit gut in schlanke CI/CD-Pipelines.

Wie starte ich den Scan nach der Einrichtung?

Mit docker compose run --rm gitleaks. --rm entfernt den Container nach dem Scan.

Kann ich nur bestimmte Commits oder Branches scannen?

Ja, mit --log-opts: --log-opts='main..feature-branch' scannt nur die Commits des Feature-Branches, --log-opts='HEAD~10..HEAD' die letzten zehn Commits. Ergänzen Sie die Option im command-Abschnitt hinter git /repo.

Welches Report-Format eignet sich am besten für CI/CD?

SARIF für GitHub Code Scanning (Upload in den Security-Tab), JUnit für Jenkins und GitLab-Testreports, JSON für eigene Auswertung oder SIEM-Anbindung.

Wie ignoriere ich bekannte False-Positives dauerhaft?

Per Fingerprint in der .gitleaksignore im Repository-Root oder per Inline-Kommentar #gitleaks:allow, der die Ausnahme sichtbar im Code dokumentiert (siehe Schritt 6).

Ist Gitleaks noch aktiv gepflegt?

Laut README ist Gitleaks „feature complete“: Neue Funktionen kommen nicht mehr hinzu, künftige Releases sind Sicherheitsupdates. Der Maintainer arbeitet am Nachfolger Betterleaks. Für das Aufspüren von Secrets reicht Gitleaks v8.x aus.

Was ist der Unterschied zwischen den Unterbefehlen `git` und `directory`?

git scannt ein Repository samt Commit-History, der Standardfall. directory (Alias files) scannt nur den aktuellen Dateistand eines beliebigen Verzeichnisses, etwa Konfigurationsordner ohne Git.

Fazit

Gitleaks findet eingecheckte Secrets schnell und ohne Infrastruktur. Das kleine Image und die fehlende Datenbank machen es zu einem einfachen Baustein für Scans auf Abruf und in Pipelines. Achten Sie auf die aktuelle Syntax (git /repo, [[allowlists]]) und prüfen Sie bei jedem Scan die Zahl der gescannten Commits. Neue Funktionen gibt es nicht mehr, Sicherheitsupdates weiterhin.

Zur Härtung des Docker-Stacks: Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only und Docker-Images auf Schwachstellen scannen mit Trivy. Secrets zentral verwalten: Infisical mit Docker: Open-Source Secrets Management.

Weiterführende Anleitungen und Quellen

Offizielle Quellen: Gitleaks GitHub README · Gitleaks GitHub Releases · Gitleaks Docker Hub