When to use
- Block committed secrets in a private or shared repository without paid GitHub Secret Protection.
- Audit a repository before it becomes public, including secrets deleted from its current files.
- Add pre-commit, pre-push, and CI checks that fail closed when the scanner cannot give a safe result.
Quick start
The skill needs Bash 3.2 or later, git, curl, and python3.
# Absolute, so the path still works after cd your-repo
SCAN="$(cd path/to/private-secret-scanning/scripts && pwd)/secret-scan.sh"
"$SCAN" install
"$SCAN" self-test
cd your-repo
"$SCAN" history --report /tmp/secret-report.json
"$SCAN" install-hooks
Three scan scopes
| Command | Scans | Use it |
|---|---|---|
staged |
The staged diff only | Fast pre-commit check |
push [RANGE] |
A named commit range, outgoing commits from pre-push input, or the full history of a new branch or tag | Catch commits made with --no-verify |
history |
Every commit reachable from any ref, including deleted files | First adoption and checks before publication |
Exit codes and fail-closed behavior
| Exit | Meaning |
|---|---|
| 0 | No leaks found |
| 1 | Leaks found. Each finding appears on stderr |
| 2 | Scanner or configuration error |
A broken scanner blocks the commit or push. The script exits 2 when it cannot trust the result, including these cases:
- Gitleaks is missing, cannot run, or does not match the pinned version.
- The configuration file is missing or malformed, or a
.gitleaks.tomlneither extends the built-in rules nor defines its own. - The scanner exit code and report disagree, or the report cannot be read as a list of findings.
- A hook finds an uncommitted suppression file or a pushed ref that is not a commit.
Reports contain no secret values
Terminal output and report files contain only RuleID, File, StartLine, Commit, and Fingerprint. They never contain the secret, matched text, or source line.
Gitleaks runs with --redact. The raw report stays in a private temporary file and is deleted on exit. The sanitized report uses file mode 0600.
Baselines and allowlists
- Rotate every live credential first. Accepting a finding does not make it safe.
- Run a history report, then copy its fingerprints into
.gitleaksignore. - Commit the ignore file so later scans report only new findings.
A custom .gitleaks.toml replaces the built-in rules unless it extends them. The script refuses a file with no rules at all, but it accepts one that defines its own [[rules]] without extending the defaults, and that file turns the built-in detectors off. Start with the default rules, then keep each exception narrow:
[extend]
useDefault = true
[allowlist]
description = "synthetic keys in test fixtures"
paths = ['''^tests/fixtures/''']
Review an ignore or allowlist change as an access-control change. Never allowlist a whole rule because it is noisy.
Hooks
install-hooks adds two repository hooks:
pre-commitruns the staged scan.pre-pushscans outgoing commits again.
The installer refuses to overwrite a hook it did not create. Add a call to the scan script inside an existing hook.
CI
Run the same script in CI so local --no-verify cannot skip the second check.
- uses: actions/checkout@v6
with:
fetch-depth: 0
- run: path/to/secret-scan.sh install
- run: path/to/secret-scan.sh history
Self-hosted runner warning: Run untrusted pull-request code only on hosted runners. A fork can rewrite the scan script and read anything a self-hosted runner can reach.
Pinned version
The script pins Gitleaks 8.30.1 and checks the SHA-256 digest for each supported Linux and macOS build. An upgrade must change the version and all four hashes together, then pass self-test. A custom GITLEAKS_BIN must still report the pinned version.
Installation
# Recommended: install the security-toolkit plugin
/plugin marketplace add jamditis/claude-skills-journalism
/plugin install security-toolkit@claude-skills-journalism
# Or copy just this skill from the plugin tree
git clone https://github.com/jamditis/claude-skills-journalism.git
mkdir -p ~/.claude/skills ~/.agents/skills
cp -r claude-skills-journalism/security-toolkit/skills/private-secret-scanning ~/.claude/skills/ # Claude Code
cp -r claude-skills-journalism/security-toolkit/skills/private-secret-scanning ~/.agents/skills/ # Codex
Works in
Uses the open Agent Skills format. Codex: candidate; selection smoke passed (October 2026).
Related skills
Scan before a secret leaves the machine
Use one pinned script for staged changes, outgoing commits, full history, hooks, and CI.
View on GitHub