diff --git a/.github/workflows/gitleaks.yml b/.github/workflows/gitleaks.yml
new file mode 100644
index 0000000..d28531d
--- /dev/null
+++ b/.github/workflows/gitleaks.yml
@@ -0,0 +1,26 @@
+name: Secret scan (gitleaks)
+
+# Scans only the commits introduced by a PR (gate before merge) so it prevents
+# NEW secrets without failing on pre-existing history. Use the manual
+# "Run workflow" (workflow_dispatch) for a full-history audit.
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Run gitleaks
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
+            LOGOPTS="--log-opts=origin/${{ github.base_ref }}..HEAD"
+          else
+            LOGOPTS=""   # manual run: full-history audit
+          fi
+          docker run --rm -v "$GITHUB_WORKSPACE:/repo" ghcr.io/gitleaks/gitleaks:latest \
+            detect --source=/repo --config=/repo/.gitleaks.toml --redact --verbose --exit-code=1 $LOGOPTS
diff --git a/.gitleaks.toml b/.gitleaks.toml
new file mode 100644
index 0000000..433ce4d
--- /dev/null
+++ b/.gitleaks.toml
@@ -0,0 +1,14 @@
+# gitleaks config — extends the built-in ruleset with project allowlists.
+title = "gitleaks config"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Allowlisted paths and known non-secret placeholders"
+paths = [
+  '''\.env\.example$''',
+  '''(^|/)env\.example$''',
+  '''(^|/)README\.md$''',
+  '''\.gitleaks\.toml$''',
+]