Files
software-infrastructure/docs/ci-cd/secret-scanning.md
T
claudeandClaude Opus 5.5 ef693ffd97 G9: reusable gitleaks secret scan, config and docs
Add a reusable workflow that downloads a pinned, checksum-verified gitleaks
and scans the pushed commits, the PR's commits, or the current tree. Logs
show only a count, never the rule, file, line or value, because the logs
are public. This repo's caller is manual-only until S8 passes.

.gitleaks.toml extends the default rules and allowlists Helm checksum/*
annotations. docs/ci-cd/secret-scanning.md covers usage, what to do when it
fails, and the policy for history scans (done privately, not in CI).

Tested locally by running the step verbatim in a container against
throwaway repos: a planted fake token fails on push, new-branch push and PR;
clean ranges, checksum annotations and this repo's tree pass; a bad
checksum fails; the value never appears in the output. actionlint and
yamllint pass.

Refs DevOps/software-infrastructure#57

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 18:44:40 -05:00

4.0 KiB

Secret scanning (G9)

Refs: DevOps/software-infrastructure#57.

CI runs gitleaks to stop new secrets from being committed. Most eom.dev repos and their Actions logs are public, so the check is built never to show a secret, or where one is, in a log.

Files

File What it is
.gitea/workflows/reusable-secret-scan.yaml Reusable workflow (workflow_call). Downloads a pinned gitleaks release, checks its SHA-256, and scans.
.gitea/workflows/secret-scan.yaml This repo's caller. Manual-only until S8 (#41) passes, then push to main and pull_request.
.gitleaks.toml This repo's config: gitleaks' default rules plus allowlists for known false positives.

What gets scanned

Event Scope
push The pushed commits (before..sha). If the push created the branch, or before isn't in the clone, the current tree.
pull_request The PR's commits (base..head).
Anything else (manual runs) The current tree only.

CI doesn't scan full history. A history scan of a public repo would put old findings into a public log. History scans are done privately (see below).

What the log shows

By default, only the number of possible secrets and the commit range or tree that was scanned. It never shows the rule, file, line or value. The failure message prints the command to run locally to see details:

docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:v8.30.1 git --redact -v /repo

show-details: true prints the rule, file and line (values stay redacted). Use it only in private repos.

Using it from another repo

Add a caller workflow and, if needed, a .gitleaks.toml at the repo root (gitleaks picks it up from the scanned directory):

name: secret-scan
on:
  push:
    branches: [main]
  pull_request:
concurrency:
  group: secret-scan-${{ github.ref }}
  cancel-in-progress: true
jobs:
  scan:
    uses: DevOps/software-infrastructure/.gitea/workflows/reusable-secret-scan.yaml@main

Calling it from another repo hasn't been tried on this Gitea yet. G2 (#50) checks how the runner resolves cross-repo uses: and from private repos, and updates this section.

Inputs:

Input Default Notes
gitleaks-version 8.30.1 Change gitleaks-sha256 with it.
gitleaks-sha256 SHA-256 of the 8.30.1 linux x64 tarball From the release's checksums.txt. Same value as images/ci-tools/Dockerfile.
show-details false See above.

Once the CI tools image (G1, #49) is published, the job can run in it and skip the download.

If the check fails

  1. Run the local command above to see what was found.
  2. If it's a real secret, rotate it first. Deleting it from git, or rewriting history, doesn't make it safe once it has been pushed to a public repo. Then move it to the vault or an Actions secret.
  3. If it's a false positive, add a narrow allowlist entry to the repo's .gitleaks.toml with a description saying why it isn't secret. Prefer a regex on the line or a path over disabling a rule. For a single known finding, its fingerprint can go in .gitleaksignore. In a public repo that names the file and commit, so use it only for false positives.

Never paste a finding into an issue, commit message, PR, or Discourse post.

Known false positives

Pattern Why it isn't secret Allowlisted in
Helm checksum/<name>: <64 hex> annotations SHA-256 of a rendered manifest, used to restart pods on change .gitleaks.toml here
Stripe publishable-key="pk_..." in HTML Publishable keys are public by design DevOps/www, when its caller is added

History scans

Done privately with the same gitleaks version, all refs, and --redact. Results go only in the private assessment, never in public issues or logs.

Date Repos Result
2026-11-14 ansible-role-{gitea,eom,www,dex,discourse,mcp-servers,prometheus,listmonk}, www, software-infrastructure Done; results are in the private assessment