Say what a gitleaks finding means when it fires

[haksungjang]

gitleaks detect scans the commits reachable from HEAD, not the checked-out files, and nothing in the failure says so. Remove the offending value, commit the removal, push, and the check fails again with the same finding, because the commit that introduced it is still on the branch. The fix looks like it was not picked up. That cost three CI rounds on #305, two of them spent editing a working tree that was already clean: run 33710943701 failed at a commit whose tree contained zero matches.

This does not change what is scanned. The current scope is right, and narrowing it to the diff would miss exactly what this check exists for, which is a secret added in one commit and deleted in a later one on the same branch. What changes is that a failure now explains itself, in a step gated on if: failure() and in a contributor-guide section for anyone searching after the fact. Both give the procedure for removing the commit rather than the value.

Both also say to rebase before collapsing commits. git reset --soft origin/main moves the branch to wherever main points now while keeping the working tree, so on a main that has advanced the resulting single commit reverts everything merged in between, silently, because the author's own files are all still correct. That happened here: 125 lines from two merged pull requests were undone that way while clearing this very finding, and the only signal was a diffstat with far more deletions than the change could account for. The guide names the two commands that catch it.

On the claim that one branch's value blocks the whole repository. That was reported, and I initially repeated it. It is not true, and the correction took two passes worth recording. Run logs first showed other branches passing while mine failed, which argued against it. A local reproduction then appeared to confirm contamination, and I nearly rewrote the scope on that basis: with a git clone, every branch becomes a local ref, gitleaks reads them all, and a finding on someone else's branch fails yours. But that is not the shape actions/checkout produces. On pull_request it fetches only the PR ref, so no other branch is present to read. Reproducing that shape gives no finding, and the run logs settle it independently: each pull request scans main's commit count plus its own (289 + n at the time), never the repository total. fetch-depth: 0 means all of this ref's history, not all branches. The comment and the guide now state that with the evidence attached, since the wrong guess is the intuitive one.

Verified: the explainer script extracted from the YAML and executed, so the heredoc renders and carries each key instruction; the workflow parses; docs-uat lint clean; a docs-site production build with no new broken anchors; ko-style and em-dash clean.