repo-healthcheck

See it in action →

Consolidates every GitHub repo you can see (and, with --gitlab, your GitLab projects too) into a single health-check view, so you can spot what's missing (README, CLAUDE.md, branch protection, license, contributors, description, topics, project structure, staleness) without clicking through each repo individually.

$ repo-healthcheck

prints a table sorted worst-first (most issues on top), so problem repos never get buried below healthy ones.

Two HTML export options:

• --html report.html -- a plain static table, every issue spelled out as text.
• --dashboard report.html -- an interactive page: a compact checklist per repo, click-to-filter chips (missing / has, multi-select), a "Forks only" / "Originals only" toggle, and click any column header to sort (click another header to add it as a tie-breaker, building a multi-column sort in click order). This is the one worth opening in a browser and actually using, not just reading.

Repo names are shown without the owner prefix for whichever account most of the report's repos belong to (hover, or the terminal table's title, still shows the full name) -- a repo under any other owner keeps owner/name so it isn't confused with that account's repo of the same short name.

What it checks

src/ layout is detected (--html shows it as a column) but never counted as an issue -- whether a repo should use one depends on its shape (a deliberate single-file tool, like this project's own source one-file-tools, correctly skips it), which isn't something to auto-enforce.

"Protected" is a specific, minimal bar, not "any protection rule exists": branch protection is on, and both force-push and branch deletion are disallowed for the default branch. It deliberately does not require PR review counts or passing status checks -- reasonable for a team, not for solo work, and this tool covers both. Also: GitHub's branch-protection API is a paid-plan feature for private repos -- it 403s with "Upgrade to GitHub Pro" regardless of your token's permissions, so most private repos on a free plan will show ? (unknown) here rather than a real answer. Public repos always get a definitive answer. (GitLab has no equivalent paid-plan gate, so ? there means a genuine permission problem, not an expected plan restriction.)

License detection has one narrow fallback beyond trusting the host's own classification. GitHub sometimes reports a standard, unmodified GNU license as NOASSERTION ("Other") -- its detector isn't perfect. Since GNU licenses always state their own name in the title ("GNU GENERAL PUBLIC LICENSE", etc.), the tool fetches the actual license file text in that case and checks for that name, resolving it to GPL / LGPL / AGPL / GFDL instead of leaving it unrecognized. This is deliberately narrow -- it isn't a general license classifier, just a targeted fix for a real, observed gap (GitHub's /license endpoint resolves the file case-insensitively; GitLab's raw-file endpoint needs the exact-cased name, recovered from a root-tree lookup done only in this fallback path). Any other unrecognized license still shows as unrecognized, as before.

Archived repos are shown but never flagged -- an archived repo won't be improved, so there's no point calling out what it's missing.

Auth

Reads GITHUB_TOKEN if set, otherwise falls back to gh auth token (so if you're already logged in via the gh CLI, no extra setup is needed). Token scope: classic repo (to see private repos) or none (public only); fine-grained needs read-only "Contents" + "Metadata".

By default it fetches everything the token can see -- your own repos plus every org you're a member of -- in one call (GitHub's affiliation=owner,collaborator,organization_member does this natively, no per-org looping needed). Pass --owner NAME to instead check one specific user's/org's public repos.

GitLab

Pass --gitlab to also fetch your GitLab projects, alongside GitHub (not instead of it) -- both appear in the same table, tagged (gitlab) / · gitlab in the renderers so they're not mistaken for GitHub repos.

$ export GITLAB_TOKEN=glpat-xxx
$ repo-healthcheck --gitlab

• --gitlab-owner NAME -- only that user's public GitLab projects, instead of everything the token can see (tokenless works here, same as --owner for GitHub, subject to GitLab's unauthenticated rate limit). GitLab groups aren't a supported target, only users.
• --gitlab-url URL -- for a self-managed GitLab instance instead of gitlab.com.
• --gitlab-token-env NAME -- if your token isn't in GITLAB_TOKEN.

Token scope: read_api. Unlike GitHub's gh auth token fallback, there's no CLI-token fallback for GitLab -- set GITLAB_TOKEN directly.

One column is always blank for GitLab rows: language, since GitLab's project-list endpoint doesn't include it (a per-project call would be needed, not worth it for one column).

Install

uv sync
uv run repo-healthcheck --help

Tests

uv run pytest