Every repository in the public record carries an embeddable badge: a small SVG showing the current health index and rating band, linking back to the full report. The badge is the record made visible where decisions happen — in the README, next to the installation instructions.
Embedding a badge
Each report page provides copy-ready snippets for its repository. The pattern:
[](https://inspect.software/software/OWNER/REPO)<a href="https://inspect.software/software/OWNER/REPO">
<img src="https://raw.githubusercontent.com/inspect-software/badges/main/v1/O/OWNER/REPO.svg"
alt="inspect.software health badge for OWNER/REPO" />
</a>Replace OWNER/REPO with the repository's full name, and O with the first character of the owner name in lowercase — badges are filed under that character so no single directory in the repository grows unbrowsable. Copying the exact snippets from the repository's report page in the public record avoids getting it wrong.
shields.io
For READMEs that standardize on shields.io badges, the record is also available through shields' endpoint badge. Every repository serves its current state as endpoint JSON at https://inspect.software/badge/v1/OWNER/REPO.json, which shields renders in its own visual language:
[](https://inspect.software/software/OWNER/REPO)The rendered badge states the same index, band vocabulary, and band color as the native badge — certified repositories lead with their letter grade — and refreshes on the same hourly schedule. All of shields' style parameters (style=, logo=, …) apply as on any other shields badge.
How badges behave
- Always current. The badge reflects the latest published inspection and updates automatically after every scan — no re-embedding needed.
- Served from GitHub. Badge images are published to the public inspect-software/badges repository and delivered by GitHub's own content network. A README carrying a badge does not depend on this site being reachable.
- Versioned path. The
/v1/path segment is stable; any future change to badge semantics arrives as a new version, never as a silent change. - Band-colored. The badge carries the color of the repository's current band, from exceptional deep green to critical red, and states the band in words beside the index.
- Certified repositories carry a seal. Repositories in the top three bands show an embossed rosette bearing their letter grade — A, AA, or AAA — the visible mark of their certification level. The seal is a certification mark, so a repository below Good does not carry one; its badge states the band and the index without it.
- One fixed size. Every badge is 137×20 pixels whatever the index says, so a README never reflows when a score moves and a row of badges stays flush.
- Never broken. A repository not yet in the record serves a neutral badge rather than a broken image.
What a badge asserts
A badge asserts exactly what the report behind it asserts: measured, publicly visible practice under a versioned methodology — and nothing more. It is a signal for review, not a warranty of quality or security (see signals, not warranties). The linked report always shows the full category profile, every metric's components, and the raw data.
Getting a badge
- Submit the repository on the home page (GitHub sign-in required).
- High public-value repositories are inspected free; others follow the certification route.
- Once the report is published, copy the badge snippets from the report page.