/ghreport

name: ghreport
description: "Read-only org repo state report. Reuses ghsync's repo discovery (teams union org-repo-list) but, instead of cloning, queries each repo's remote GitHub state - open PRs, CI on the default branch, open security alerts (Dependabot / code-scanning / secret-scanning), and branch protection - and rolls it into a terminal summary plus a timestamped markdown file. Endpoints that need admin and return 403/404 are reported as no-access / unknown, never as a clean zero. TRIGGER when the user types /ghreport, asks 'what state are the org's repos in', wants an org health report or repo state snapshot, or asks about open PRs / failing GitHub Actions / security alerts across a whole org or personal account."

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. 2. **Read the headline** - the counts of repos with failing CI, open alerts, and an unprotected default branch. These are the repos that need attention. 3. **Surface the "Needs attention" list** to the user verbatim; that is the actionable core of the report. 4. **Point at the saved file** (`org-state-<org>-<date>.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-<org>-<YYYY-MM-DD>.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.