Secret scanning

The goal is to keep credentials out of repositories. Scanning is the check; the design rule comes first:

Credentials live outside the repo tree. Code reads them from paths or environment variables that point outside the repository (for example $HOME/.pi-web-ui/internal-api-token), and should refuse a credential path that resolves inside its own repo. .gitignore is only a backstop: one git add -f or one renamed file defeats it.

The tool: gitleaks

gitleaks is a single binary and needs no account or human step. Check it with gitleaks version. If it is missing, install a pinned release and verify the checksum:

V=8.30.1; D=$(mktemp -d); cd "$D"
curl -sSfL -o gl.tgz "https://github.com/gitleaks/gitleaks/releases/download/v$V/gitleaks_${V}_linux_x64.tar.gz"
curl -sSfL -o sums.txt "https://github.com/gitleaks/gitleaks/releases/download/v$V/gitleaks_${V}_checksums.txt"
grep "gitleaks_${V}_linux_x64.tar.gz" sums.txt | sed "s/gitleaks_${V}_linux_x64.tar.gz/gl.tgz/" | sha256sum -c -
tar xzf gl.tgz gitleaks && install -m 0755 gitleaks /usr/local/bin/gitleaks; cd /; rm -rf "$D"

Never print a secret

Always pass --redact. Never print, paste, quote or store a matched value, including in reports, commit messages, chat or evidence files. Not even partly, and not "masked in context". Triage from metadata only: rule id, file, line, commit, the key name that matched, and whether the file still exists at HEAD. On some hosts the agent's permission layer blocks commands that would expose credential values. Treat that block as correct; do not work around it.

Commands

Exit code 1 means findings; 0 means none were found.

Triage

Classify every finding. Most hits of the broad generic-api-key rule are harmless.

1. Identifier false positive: idempotency keys, UUIDs, digests, config words (for example NoNewPrivileges). Allowlist them.
2. Deliberate test fixture: a fake key planted to test redaction. Prefer an obviously fake shape (TEST-FAKE-…), and allowlist it.
3. Possibly real: anything else, especially in docs, scripts, logs or evidence. Treat it as real until the operator confirms otherwise.

For a possibly real credential:

• Rotate or revoke it first. Rewriting history does not un-leak a secret that was ever public: clones, forks and caches keep it.
• Then tell the operator, with the location (file, line, commit), never the value.
• Rewriting history (git filter-repo) and force-pushing are the operator's decision. Never do them unasked.

Allowlisting without hiding real leaks

• .gitleaksignore holds finding fingerprints (commit:file:rule:line, no secret values). Add a fingerprint only after triage says it is a false positive or a fixture.
• An inline gitleaks:allow comment on a fixture line also works.
• Baseline for legacy history: gitleaks git --report-path baseline.json … once, then run --baseline-path baseline.json in CI, so only new findings fail. A baseline accepts the old findings; triage them before baselining, and never baseline a possibly real credential.

CI and hooks

GitHub Actions (the official action needs no licence for a personal account's repo):

  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 }}" }

A local pre-commit hook (.git/hooks/pre-commit) is a personal choice: describe it in the repo's maintainer docs, and don't install it into someone else's clone:

#!/bin/sh
exec gitleaks git --pre-commit --staged --redact

Before publishing checklist

1. gitleaks git --redact -v . over full history, then gitleaks dir --redact ..
2. Grep for host-specific or personal data a scanner won't flag: absolute host paths, internal hostnames, emails, real session ids, private repo names.
3. Confirm code reads credentials only from outside the repo, and prove the tests pass on a machine without your private checkout (for example, HOME pointed at an empty temp dir).
4. Add the CI job.
5. An independent reviewer re-runs the scan before the first public push.

This skill is the pre-publication check used by the Pi Web UI orchestration pack: scan the artefacts a wave produced before they leave the machine.