# GitHub badges

> Embeddable inspect.software badges — a live health signal for any inspected repository, updated automatically after every scan. Markdown and HTML snippets.


Every repository in the public record carries an embeddable **badge**: a
small SVG showing the current health index and
[rating band](/wiki/scoring-bands), 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:

```markdown
[![inspect.software](https://raw.githubusercontent.com/inspect-software/badges/main/v1/O/OWNER/REPO.svg)](https://inspect.software/software/OWNER/REPO)
```

```html
<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](/#record) avoids getting it wrong.

## shields.io

For READMEs that standardize on [shields.io](https://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:

```markdown
[![software health](https://img.shields.io/endpoint?url=https%3A%2F%2Finspect.software%2Fbadge%2Fv1%2FOWNER%2FREPO.json)](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](https://github.com/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](/wiki/certification-levels). 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](/methodology) — and nothing more. It is a signal for
review, not a warranty of quality or security
(see [signals, not warranties](/wiki/signals-not-warranties)). The linked
report always shows the full category profile, every metric's components,
and the raw data.

## Getting a badge

1. Submit the repository on the [home page](/) (GitHub sign-in required).
2. High public-value repositories are inspected free; others follow the
   [certification route](/pricing).
3. Once the report is published, copy the badge snippets from the report
   page.