Repo Health Check for public GitHub repositories

Before you hand a project to a new developer, or before you agree to take one on, it helps to know what state the repository is in. This tool reads a public GitHub repository through GitHub's public API and turns what it finds into a handover-readiness score from 0 to 100, with a short fix for each weak signal. It reads metadata and file names only. It does not clone, build or run the code.

What the check looks at

• Last commit. How long ago someone last pushed to the default branch. A long gap is not a problem in itself, but it tells the next developer that dependencies and hosting may have drifted.
• Commit frequency. Whether work happened steadily or in a few large bursts. Bursts often mean big, hard-to-review changes.
• Contributors. How many people have committed. A project written by one person carries more hidden knowledge that needs to be written down before handover.
• Open issues. A long list of untriaged issues hints at known problems nobody has sorted. A short, labelled list is a good sign.
• README and LICENSE. Whether the basics exist so a newcomer can understand what the project is and who may use it.
• Tests and CI. Whether test files or folders exist, and whether a pipeline such as a GitHub Actions workflow runs on each push.
• Committed secret files. File names such as .env, .env.production, private key files or service account JSON files that usually hold credentials.
• Dependency manifests. Files such as package.json, lockfiles, requirements.txt, pubspec.yaml, composer.json or go.mod, which tell a developer how to install the project.
• Language mix. GitHub's own breakdown of languages in the repo, which shows the real stack at a glance.

How to read the score

The score is a weighted summary of the signals above. Read it as a rough handover forecast, not a grade:

• High score: a newcomer can probably clone, install and find their way around quickly.
• Middle score: workable, but expect setup time and a few questions for the previous developer.
• Low score: plan a paid discovery phase before anyone estimates new features.

The individual findings matter more than the number. One committed secret file outweighs a missing licence. A missing README on a small project is easy to fix; missing tests on a large one shape the whole estimate. Results are guidance, not a security audit or a code review.

Fixing the common findings

A .env or key file is committed

Deleting the file in a new commit is not enough, because it stays in the history. First rotate every credential the file contained, then remove it from history with git filter-repo or BFG, add the file name to .gitignore, and commit a .env.example that lists variable names with no values. Paste your config into the Secret Leak Scanner to see which values are real keys. Our guide on giving a developer access without sharing passwords covers where the values should live instead.

No README, or a thin one

A useful README answers: what the app does, how to run it locally, which environment variables it needs (names only), how it is deployed, where it is hosted, and what is known to be broken. Twenty honest lines beat a page of marketing copy.

No tests or CI

You do not need full coverage before a handover. A few smoke tests for login and the main flow, plus a workflow that installs dependencies and builds on every push, give the next developer a safety net and catch broken builds early.

No LICENSE

For a private commercial product you may not want an open-source licence at all. What matters for a handover is that ownership of the code is written down in your agreement with the developer. See paying a developer safely for what that agreement should cover.

Stale activity

If the last commit is old, check that dependencies still install and that the hosting account is still active before you promise anyone a start date. The Dependency Freshness Check helps with the first part.

Limits you should know about

• Public repositories only. Unauthenticated calls cannot see private repos. Do not make a private repo public just to run this check; invite a reviewer as a read-only collaborator instead.
• Rate limits. GitHub allows a small number of unauthenticated API requests per hour for each IP address, currently 60. A single check uses several, so a few checks in a row can hit the limit. The tool shows when you can try again.
• Default branch only. Work sitting in other branches is not counted.
• Pattern-based detection. Tests, CI files or manifests in unusual locations may be missed, so a "missing" finding is worth a quick manual look.

For developers assessing a takeover

If you are the one deciding whether to take on a project, run this check before the first call and bring the findings to it. It turns vague questions into specific ones: "Who set up this workflow?" or "Why is there a service account file in the root?" Our guides on assessing a takeover before you commit and your first week on an inherited codebase explain what to do with the answers.

Stuck with a repo nobody is working on?

If your score is low because the original developer stopped responding, start with what to do when a developer disappears with the code. When you are ready for someone new to pick it up, post your takeover for free and include your score and findings so developers can see the real state from the start.