Repository health score

Repository health score is a weighted composite that combines several quality and maintenance signals into a single 0 to 100 grade for a code repository. A repository with strong test coverage, up-to-date dependencies, fast review turnaround, and few stale issues scores high. One with failing tests, abandoned pull requests, and security alerts left open scores low. The number is a summary, not a measurement of one thing.

It matters because code quality is otherwise invisible until it causes an incident. A repository can look fine on the surface while accumulating outdated dependencies, untested paths, and a backlog of unreviewed changes. The health score surfaces that decay early, before it turns into a security breach, a failed deploy, or a feature that takes three times as long to ship as it should.

The score is most useful as a trend, not an absolute. A single repository at 72 tells you little. The same repository sliding from 85 to 72 over a quarter tells you maintenance is being deferred, and a portfolio view across dozens of repositories tells you where engineering time is most at risk. It complements delivery metrics like deployment frequency by explaining whether speed is being bought at the cost of accumulating risk.

There is no universal definition of the components or their weights. One organisation might weight security alerts heavily because it operates under strict compliance, while another weights documentation and onboarding signals because it relies on many contributors. The score is only meaningful when the rubric is written down and applied consistently across every repository being compared.

Because it is a composite, the headline number can hide as much as it reveals. A repository can hold a respectable score while one critical dimension, say security, is quietly failing, because strong scores elsewhere mask it. This is exactly why the score should always be read together with its components rather than on its own.

Pick the dimensions that represent health for your context, normalise each to a 0 to 100 scale, assign a weight to each so the weights sum to 1, then take the weighted sum. The result is the repository health score. The art is in choosing components that are both meaningful and measurable from data you already collect in version control and CI.

The inputs below are a common starting set. Adapt the list and the weights to your engineering standards, but write them down so the score stays comparable as the team and the codebase change.

1. 1

   Select health components

   Choose the dimensions that define a healthy repository for you, such as test coverage, dependency freshness, security alert backlog, review discipline, build pass rate, and documentation completeness.

2. 2

   Normalise each component to 0 to 100

   Convert each raw signal to a common scale. For example, map test coverage directly, and convert the count of overdue security alerts into a score where zero alerts is 100 and a defined threshold is 0.

3. 3

   Assign weights that sum to 1

   Decide how much each component contributes. Security and test coverage often carry more weight than documentation. The weights encode your engineering priorities and must total 1.

4. 4

   Take the weighted sum

   Multiply each normalised component score by its weight and add them together. The result is a single 0 to 100 figure you can track per repository and roll up across a portfolio.

A composite score is the natural top of a metric tree, because it is built from components by definition. Each component becomes a first-level driver, and each driver decomposes into the concrete signals an engineer can change. This makes the score diagnostic rather than merely descriptive: a low number always traces to a specific branch.

Because the rubric is bespoke, cross-organisation benchmarks should be treated as rough guidance rather than targets. What matters most is the band a repository sits in and the direction it is moving. The ranges below describe how to read a 0 to 100 score once your weights are fixed and applied consistently.

Improving the score means raising the weakest weighted components, not polishing the ones already strong. Read the tree, find the branch dragging the number down, and direct effort there. The cards below cover the moves that most often shift a struggling repository back into a healthy band.

1. 1

   Re-weighting to flatter a repository

   Adjusting the weights so a struggling repository scores well turns the metric into theatre. Fix the rubric once and let the number tell the truth.

2. 2

   Reading the headline without the components

   A strong average can hide a failing security component. Always inspect the branches before concluding a repository is healthy.

3. 3

   Treating the score as a leaderboard

   Ranking teams on a composite encourages gaming the easiest components rather than fixing real risk. Use the score to guide work, not to score people.

4. 4

   Ignoring the trend

   A static snapshot misses the story. A repository sliding from 85 to 70 needs attention even though it still looks acceptable in absolute terms.