diff --git a/.github/public-repo-hygiene/README.md b/.github/public-repo-hygiene/README.md index b7a27b7..9ef696e 100644 --- a/.github/public-repo-hygiene/README.md +++ b/.github/public-repo-hygiene/README.md @@ -29,6 +29,35 @@ string is scanned in place of the file body. A regular file is read up to `MAX_F and no further, and what is *derived* from those bytes is capped too — `MAX_FINDINGS_PER_FILE` (200), `MAX_FINDINGS_TOTAL` (2000) and a `MAX_EXCERPT_CHARS` (200) bound on the echoed line, since a category-2 finding copies the matched line and the scanned repo controls how long that is. + +## Surfaces scanned + +Three surfaces, all sharing one matcher (`_line_findings`) so they can never drift apart: a +tracked file's **contents**, its tracked **path** string (BE-9399), and the **PR title and +description** (BE-9652). + +PR text is scanned when the triggering event carries a pull request. It is published the moment it +is typed and no file scan can ever see it — both leaks that motivated this were on a public PR of +`github-workflows` itself: an internal collaboration-tool permalink in a description, and a +non-public org repo named in a body. + +Three properties are deliberate: + +- **Categories 2 and 3 only — never category 1.** This org's commit convention *requires* a + `(BE-####)` Linear suffix on PR titles, so ticket ids there are org-wide practice, not a leak; + half of this repo's own recent merged PR titles carry one. Flagging them would fail roughly every + second PR, and a required check that fires on correct behaviour does not get fixed — it gets + switched off, taking the two categories that catch real leaks with it. A test pins this. +- **Read from the event, never from a workflow input.** A caller that could supply the text being + judged could supply *different* text. Same reasoning as loading this checker from `workflows_ref` + rather than the caller's checkout. +- **Passed to the checker as file paths, never as argv values.** PR text is unbounded, + author-controlled and full of shell metacharacters; the workflow writes it from `env:` to + `RUNNER_TEMP` and passes `--scan-text '