bjcoombs ghreport: what state are an org's repos in?
ghsync answers "do I have all the code locally and up to date?" ghreport
answers the companion question: "across everything I can see, what needs
attention right now?" It is read-only - it never clones, pulls, or mutates
anything.
It reuses ghsync's discovery so the team-union / org-repo-list logic lives in
exactly one place: ghreport shells out to ghsync --porcelain to get the
deduplicated repo list, then queries each repo's remote state over gh api.
What it reports, per repo
| Signal | Source | Reported as |
|---|---|---|
| Open PRs | repos/{o}/{r}/pulls?state=open |
count (drafts noted) |
| CI on default branch | latest completed run per workflow on the default branch | pass / fail (names the failing workflows) / none |
| Security alerts | Dependabot + code-scanning + secret-scanning, ?state=open |
three counts, or n/a (no-access) |
| Branch protection | repos/{o}/{r}/branches/{default}/protection |
protected / unprotected / unknown |
The no-access rule
Security-alert and branch-protection endpoints require admin on the repo. When
the caller is denied (403/404), ghreport reports n/a (alerts) or
unknown (protection) - never a clean 0. Reporting "no access" as "no
problems" would be a dangerous lie, so the two are kept distinct. A repo whose
own metadata can't be read at all is listed as could not assess.
How to run it
The script lives next to this file. Resolve its directory the same way the
other skills do (works whether installed as a plugin or hand-placed under
~/.claude/skills/):
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/ghreport}"
SKILL_DIR="${SKILL_DIR:-$(dirname "$(realpath ~/.claude/skills/ghreport/SKILL.md)")}"
# Org is derived from the directory you run in, exactly like ghsync. To report
# on the "meridianhub" org, run from a directory named meridianhub:
cd ~/dev/github.com/meridianhub
bash "$SKILL_DIR/scripts/ghreport.sh"
Override the org or target directory explicitly when they differ:
bash "$SKILL_DIR/scripts/ghreport.sh" --org meridianhub --root ~/dev/github.com/meridianhub
What to do when invoked
- Run it from (or pointed at) the org directory. It streams a progress dot per repo, then prints the summary.
- Read the headline - the counts of repos with failing CI, open alerts, and an unprotected default branch. These are the repos that need attention.
- Surface the "Needs attention" list to the user verbatim; that is the actionable core of the report.
- Point at the saved file (
org-state-<org>-<date>.mdin the root) for the full per-repo table.
Flags
| Flag | Effect |
|---|---|
--org NAME |
Org or personal account to report on (default: basename of --root / cwd) |
--root DIR |
Org root; also where the report file is written (default: cwd) |
--limit N |
Only the first N repos (quick test against a large org) |
--quiet |
Suppress the per-repo progress dots; keep the summary and file |
--no-file |
Terminal only; do not write the markdown file |
--render-dir DIR |
Skip discovery + querying and render a report from a directory of previously-collected per-repo JSON fragments (replay / testing) |
Output
- Terminal: a one-line headline (counts that tripped a signal), a rollup table, and a "Needs attention" section listing only the repos with an issue.
- File (unless
--no-file):org-state-<org>-<YYYY-MM-DD>.mdin the root, with the full table and per-section detail.
Requirements
ghandjqonPATH, andgh auth statusauthenticated (the same prerequisites asghsync; discovery is delegated to it).- For a GitHub Enterprise host, set
GH_HOSTorgh auth login --hostnamefirst, as withghsync. - Very large orgs make many REST calls (~5 per repo); use
--limitto sample.