gitleaks scans every branch, so one false positive on any branch turns hygiene red on every PR

[kyle-sexton]

Summary

The hygiene job's secret scan is failing on open PRs for a finding that belongs to a
branch those PRs do not contain. As of this writing that is every PR CI runs, plus main's
next push. The finding itself is a false positive.

Reproduction

.github/workflows/ci.yml:137-144 runs the scan with scan-mode: git. In that mode
gitleaks walks the commits reachable from all refs in the clone, not the checked-out
ref. actions/checkout with fetch-depth: 0 fetches every branch, so each PR's scan
covers unrelated in-flight branches.

Reproduced locally against gitleaks 8.30.1, the version CI installs:

# only origin/main plus the PR branch present
$ gitleaks git --config .gitleaks.toml --redact
INF 1977 commits scanned.
INF no leaks found

# after git fetch origin '+refs/heads/*:refs/remotes/origin/*'
$ gitleaks git --config .gitleaks.toml --redact
INF 2018 commits scanned.
WRN leaks found: 1

Same config, same binary, same checked-out commit. The only variable is which other
branches happen to be in the clone.

The finding

RuleID : generic-api-key
File   : plugins/claude-config/lib/resolve-convention-home.sh
Line   : 248
Commit : f7aec1549dec60407a24a7d8ea720696b7b099af
Branch : chore/retired-conventions-mechanism
Match  : CLAUDE_TOKEN=""

The matched text is an empty shell variable initialisation, next to its sibling on the
line above:

AGENTS_STATE="none"; AGENTS_TOKEN=""
CLAUDE_STATE="none"; CLAUDE_TOKEN=""

These are parser state variables for a file scan. There is no credential here, and the
assigned value is the empty string, so nothing is disclosed. generic-api-key fired on
the identifier alone.

Neither the file nor the line exists on main, which is why main's last push run
(33562372229, f43bd07, 21:40Z) was green and PR runs started failing at 22:12Z: the
commit landed on its branch at 21:47Z, between the two.

Two separate defects

1. The false positive. CLAUDE_TOKEN="" is a state variable, not a secret.
2. The blast radius. A finding on any branch fails hygiene on every other branch. A
   contributor sees a red check citing a file their PR never touched, which is the part
   that actually costs time. Defect 1 is a one-line fix on one branch; defect 2 will do
   this again on the next false positive.

Options

For the finding, per .gitleaks.toml's own policy ("Intentional findings use a
repository-owned .gitleaksignore or inline gitleaks:allow comment"), an inline
# gitleaks:allow on that line in the owning branch is the narrower of the two and does
not need a fingerprint that goes stale when the commit is rebased.

For the blast radius, scan-mode: git could be scoped to the range under review
(--log-opts over the PR's own commits) so a PR is judged on its own diff, with
full-history scanning kept on the main-branch push run where it still catches
history rewrites. That is a change to the shared ci-workflows action's contract or its
inputs, so it wants its own decision rather than a drive-by edit.

Not fixed here

Neither fix belongs in an unrelated PR: the false positive is on a branch whose author
should decide the annotation, and the scoping change touches shared CI. Filed so the
red check has an owner instead of being re-diagnosed by whoever hits it next.

[kyle-sexton]

What the rule actually matched, and why an inline allow is not enough on its own

Two corrections to the original report, both from reproducing against gitleaks 8.30.1.

The "secret" is the next line

Unredacted, the finding spans two lines:

Rule   : generic-api-key
Line   : 248 - 249
Match  : 'CLAUDE_TOKEN=""\nCLAUDE_SHIM=0'
Secret : 'CLAUDE_SHIM=0'

generic-api-key keys on the TOKEN identifier and then reaches forward for
something quoted-or-assigned to call the value. What it settled on is
CLAUDE_SHIM=0, the integer flag on the following line. So the finding is not
"an empty assignment looks like a credential" as first described; it is the
keyword on line 248 capturing an unrelated line 249. The assigned value on 248 is
still the empty string, and nothing is disclosed either way.

Worth noting for anyone reproducing: the two lines in isolation do not fire.
A minimal three-line fixture scans clean. The rule only triggers with the real
file's surrounding content, so a reduced repro will mislead you into thinking it
is already fixed.

An inline gitleaks:allow does not clear a finding already in history

This is the part that changes the fix. Measured on a fixture holding the real
file, with the annotation added in a later commit:

Scan mode	Result
git (what CI runs)	1 leak — the earlier commit's patch still carries the unannotated line
dir (working tree)	0 leaks — the annotation is respected

scan-mode: git reads commit patches, not the checked-out file, so annotating in
a follow-up commit leaves every already-pushed commit flagged for as long as it
stays reachable.

What this means for the two fixes

• The annotation is still necessary, and for a reason the first write-up
  missed: without it, the squash-merged commit that lands on main carries the
  bare line, and main goes red permanently rather than transiently. Prepared
  as a 6-line commit (annotation plus a comment recording why), verified dir
  mode clean with it and flagged without, resolver suite 61/61, shellcheck clean.
  Not pushed: it belongs to feat: ship the retired-conventions mechanism (Phase 2b) #3597's branch, and pushing to a branch other than
  the one this session was assigned needs its owner's say-so.
• The annotation alone does not unblock the currently-red PRs. Only removing
  the unannotated commit from every scanned ref does that, which means either
  rewriting that branch's single commit or waiting for feat: ship the retired-conventions mechanism (Phase 2b) #3597 to squash-merge and
  its branch to be deleted.
• Which makes the scoping change the load-bearing item rather than the nice-to-have.
  Judging a PR on its own commit range would have made this a non-event: the
  finding would have failed exactly one PR, the one that introduced it, instead
  of every open PR in the repository.

---

Generated by Claude Code

[kyle-sexton]

The per-commit fix does not converge, and there is now evidence

The annotation landed on chore/retired-conventions-mechanism (f7aec154 amended in
place to f3d0a223, author preserved, delta exactly the six lines). That should have
been the end of it. It was not, for two reasons that between them make the case for the
scoping change rather than more annotations.

The commit stayed reachable

chore/bespoke-conversion was stacked directly on the pre-amend commit, so the old
f7aec154 survived on that ref. It was then merged forward rather than rebased
(38fcb185, "Merge remote 2b (gitleaks annotation) keeping the CI repairs"), which is
the right call for a branch someone else has checked out and which correctly preserved
CI repairs made in parallel. It also means a merge keeps the unannotated commit
reachable by construction. f7aec154 is currently reachable from three refs:

refs/remotes/origin/chore/bespoke-conversion
refs/remotes/origin/chore/pilot-plugin-quality
refs/remotes/origin/chore/retired-conventions-mechanism

Annotating the source does not retract a commit. Only rewriting every ref that carries
it does, and on a stack with concurrent work that is a fight you keep re-fighting.

The finding multiplied

The scan now reports two, not one:

708739fb2ba1  line 249  plugins/plugin-quality/lib/resolve-convention-home.sh
f7aec1549dec  line 248  plugins/claude-config/lib/resolve-convention-home.sh

The second is the same file vendored into another plugin on chore/pilot-plugin-quality,
carrying the same CLAUDE_TOKEN / CLAUDE_SHIM pair. This file is explicitly a
shared-source candidate ("the first consuming plugin adds both in the same change that
copies it"), so every future consumer that copies it before the annotation reaches them
adds another finding, each on its own branch, each failing hygiene for every other branch.

What this changes

The scoping change is not the tidier of the two options, it is the only one that
terminates. Judging a PR on its own commit range would have made both of these findings
fail exactly the branch that introduced them, where the author can see and fix them,
instead of failing every open PR in the repository and sending whoever hits it first on
a cross-branch archaeology run.

Until that lands, hygiene stays red repo-wide, including on PRs whose diffs touch none
of this. That is worth knowing before someone reads a red check as their own defect.

The remaining per-commit cleanup belongs to the branches that own those commits, and is
being actively worked there.

---

Generated by Claude Code

[kyle-sexton]

PR #3618 (commit 220bd3bc) adds a repository-owned .gitleaksignore recording both current fingerprints:

f7aec1549dec60407a24a7d8ea720696b7b099af:plugins/claude-config/lib/resolve-convention-home.sh:generic-api-key:248
708739fb2ba1b0196e93f9c07d3293bddfeed2f0:plugins/plugin-quality/lib/resolve-convention-home.sh:generic-api-key:249

This is the third mechanism .gitleaks.toml's own policy names, and unlike the inline annotation it does clear findings already in history: gitleaks reads the ignore file from the checked-out tree, so any branch carrying it scans clean regardless of which refs hold the unannotated commits. Verified with gitleaks 8.30.1 over all 29 remote refs: 2 leaks without the file, 0 with it. Other open PRs pick it up by merging main once #3618 lands.

This unblocks PRs; it does not close this issue. The scoping change (judging a PR on its own commit range) is still the fix that terminates, since each future false positive needs a new fingerprint here until it lands. The entries can be deleted once their commits stop being reachable.

---

Generated by Claude Code