Ghreport

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

1. Run it from (or pointed at) the org directory. It streams a progress dot

per repo, then prints the summary.

1. Read the headline - the counts of repos with failing CI, open alerts,

and an unprotected default branch. These are the repos that need attention.

1. Surface the "Needs attention" list to the user verbatim; that is the

actionable core of the report.

1. Point at the saved file (org-state--.md in 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--.md in the root,

with the full table and per-section detail.

Requirements

• gh and jq on PATH, and gh auth status authenticated (the same

prerequisites as ghsync; discovery is delegated to it).

• For a GitHub Enterprise host, set GH_HOST or gh auth login --hostname

first, as with ghsync.

• Very large orgs make many REST calls (~5 per repo); use --limit to sample.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bjcoombs
• Source: bjcoombs/ai-native-toolkit
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.