docs(dependabot): a fine-grained token cannot read private check runs

[twistedmelonman]

The digest tokens need Contents and Commit statuses — and the digest still
cannot survey private repositories, because the last permission it needs does
not exist on a fine-grained token.

A fine-grained PAT has no Checks permission at all
(community#129512).
GitHub Actions results are check runs, so no scoping lets one read them on a
private repo. An earlier revision of this PR said to grant "Checks and Commit
statuses"; half of that was impossible. It is removed rather than softened.

Probed 2026-09-11 against nightowlstudiollc/kebab-tax-netlify#280 with all
four grantable permissions in place:

Endpoint	Result
pulls/280	ok
commits/<sha>	ok — Contents
commits/<sha>/status	ok — Commit statuses
commits/<sha>/check-runs	DENIED — ungrantable

The denial is silent, which is the danger. GitHub answers statusCheckRollup
with HTTP 200 and the correct totalCount, then nulls every CheckRun. That PR
has 12 contexts; 11 came back null and one Netlify StatusContext survived, so
seven failing builds and a green required check read as "1 failing check, 0
required checks". A PR with no Netlify status — most of the fleet — reads as
entirely green.

#134 is the code-side defence against that (collect refuses, classify buckets,
render warns). This PR is the documentation side: it records the finding and
states the remaining choice as an open decision rather than a step to follow.

Open decision, for @smartwatermelon:

Option	Trade-off
Classic PAT	Reads everything, but carries write access fleet-wide for a read-only report
GitHub App	Apps do have a Checks permission; correct shape, more setup
Public-only	Keep the current tokens; digest states plainly that private repos are unsurveyed

Until that is decided the workflow keeps failing on private repos rather than
publishing a partial digest.

Advances #120.

https://claude.ai/code/session_01ESsw699T54JHARkQXrdL3o

[twistedmelonman]

Correction: Contents was necessary but not sufficient

The tokens were granted Contents: read and the run still fails with the
same FORBIDDEN on nightowlstudiollc/kebab-tax-netlify#280. The title
overstated what was established, and is now corrected.

What the grant did change, measured against the live token after the edit:

kebab-tax-netlify  private  commits=ok  pulls=ok
cleanroom          private  commits=ok  pulls=ok
amelia-boone       public   commits=ok  pulls=ok

So the REST reads all pass and the visibility theory is dead too. The runbook
change here stands on its own — the collector genuinely does read
pullRequest.commits, and Contents genuinely does gate it — but it is not the
whole answer.

What was never tested, and is the actual gap: the full pr_detail_query
has only ever run in CI. The local dry run used a broad personal login for all
three owners, and the probes above used REST plus a cut-down GraphQL query. The
real query adds statusCheckRollup, isRequired(pullRequestNumber:) and
checkSuite — and since smartwatermelon has no open PRs and
kebab-tax-netlify#280 sorts first under nightowlstudiollc, that query has
never once succeeded in CI under a fine-grained token. "It works on
amelia-boone" was a REST result, not a detail-query result.

A bisect of that query against the real token is running now. Holding this PR
until it names the permission, rather than merging a runbook that says "add
Contents" to someone who just did.

[twistedmelonman]

Resolved — the bisect completed and this PR was rewritten to match its result. The hold in my earlier comment is lifted.

What the bisect named. Probing the four REST endpoints against the live token on nightowlstudiollc/kebab-tax-netlify#280, with Contents and Commit statuses both granted:

pulls/280                  ok      <- Pull requests
commits/<sha>              ok      <- Contents
commits/<sha>/status       ok      <- Commit statuses
commits/<sha>/check-runs   DENIED  <- Checks

check-runs is the one that fails, and it is ungrantable: fine-grained PATs have no Checks permission at all (github.com/orgs/community/discussions/129512). That is why granting Contents did not fix it — Contents was necessary and never sufficient, and the missing piece was never a grant anyone could add.

This also corrected a claim I had made earlier in the thread: Commit statuses is grantable and now works. Only Checks is impossible.

Why the probes looked like they passed. They never exercised statusCheckRollup. GitHub does not refuse that field — it answers HTTP 200 with the correct totalCount and nulls every CheckRun. On that PR, 11 of 12 contexts came back null; only a Netlify StatusContext survived. Seven failing builds and one green required check presented as "1 failing check, 0 required checks".

The diff was rewritten, not just re-titled. The commit that said "needs Checks and Commit statuses too" was amended (it had never been pushed). The runbook no longer instructs anyone to grant Checks; it has a What a fine-grained token cannot do section stating the limit, the measurement, and the three ways forward as an open decision. The four-endpoint probe survives with its check-runs row corrected to say there is nothing to grant.

Superseded in part. #134 (merged) is the code-side defence: collect.sh refuses a rollup containing a nulled context, classify.sh buckets it checks-unreadable, render.sh warns. #135 plans the migration to a GitHub App, which does have a Checks permission. This PR is the documentation of the finding, and main's runbook is currently wrong without it — it still says "exactly two" permissions.