docs: refocus the README and add a read-only token option - #14
Merged
Conversation
Restructure the README around a one-line install, GitHub auth setup, what the tool reads from GitHub vs. what it reports, opening the report in a browser, and a tight telemetry/opt-out section. Document a read-only fine-grained token alongside gh auth login. Also fix the stale "current directory" claim in analyze.sh: the binary writes its report to a temp dir and prints the path.
The token prompt only described the classic `repo` path, which is read+write. Add the read-only fine-grained alternative (Contents, Pull requests, Administration, Dependabot alerts) to both the gh and PAT instructions, and note that the CLI only ever reads.
blimmer
marked this pull request as ready for review
May 26, 2026 20:03
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A documentation pass on the README, plus matching in-CLI guidance. The README is restructured around a one-line install, GitHub auth setup, what the tool reads from GitHub vs. what it reports, opening the report in a browser, and a tight telemetry/opt-out section. Since the tool only ever reads from the API, it now documents a read-only fine-grained token alongside
gh auth login, with permissions verified against GitHub's fine-grained permissions reference. Also fixes a stale "current directory" claim inanalyze.sh(the report goes to a temp dir).Review focus
The token guidance is the one judgment call worth a hard look. Classic
repo/gh auth logincan't be read-only — GitHub has no read-only classic scope for private repos — so the least-privilege path requires a fine-grained token with Contents, Pull requests, Administration, Dependabot alerts (all read). I keptgh auth loginas the easy path and added fine-grained as the opt-in least-privilege option rather than forcing it, because fine-grained tokens carry org-approval friction. Two things to sanity-check: (1) whether that framing is the right default, and (2) whether Administration: read is an acceptable ask — it's only needed for the branch-protection coverage metric, and the name sounds heavier than the others even though it's read-only.Commits
15545d7— docs: rework the README and fix the analyze.sh output commentba9715f— docs: offer a read-only fine-grained token in the CLI walkthrough