Skip to main content
Add a health badge to your README to show your project’s code health at a glance. 
fallow health --format badge > badge.svg
The badge displays the letter grade and numeric score in shields.io flat style:
zod: B (71)preact: B (76)svelte: B (73)vite: C (65)
Grades: A (≥85, green) · B (70–84, green) · C (55–69, yellow) · D (40–54, orange) · F (<40, red).

​
Hosting the badge

The SVG needs a stable URL for your README to reference. Three options, from simplest to most robust:

​
Option 1: Commit to your repo

Generate the badge and commit it directly: 
fallow health --format badge > .github/badges/health.svg
git add .github/badges/health.svg
git commit -m "chore: update health badge"
Then reference it in your README: 
![fallow health](.github/badges/health.svg)
This is the simplest approach but the badge only updates when you regenerate and commit. Because it is a relative link to a file committed in your repo, it also renders in private repositories (see Private repositories below). Add a step to your CI workflow that generates the badge and publishes it to a badges branch: 
- name: Generate health badge
  run: fallow health --format badge > badge.svg

- name: Publish badge
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: .
    publish_branch: badges
    keep_files: true
    include_files: badge.svg
Then reference the badge from the badges branch:
![fallow health](https://raw.githubusercontent.com/your-org/your-repo/badges/badge.svg)
raw.githubusercontent.com URLs only render for public repositories. On a private repo the badge shows as a broken image, because GitHub’s markdown renderer cannot authenticate to the raw host. See Private repositories.

​
Option 3: Shields.io endpoint

If you prefer dynamic badges via shields.io, generate a JSON endpoint file instead: 
fallow health --format json --score --quiet 2>/dev/null \
  | jq '{schemaVersion: 1, label: "fallow", message: "\(.health_score.grade) (\(.health_score.score | floor))", color: (if .health_score.score >= 85 then "brightgreen" elif .health_score.score >= 70 then "green" elif .health_score.score >= 55 then "yellow" elif .health_score.score >= 40 then "orange" else "red" end)}' \
  > health-badge.json
Host the JSON file (e.g., in a Gist or on the badges branch) and use the shields.io endpoint badge: 
![fallow health](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/your-org/your-repo/badges/health-badge.json)
This keeps the badge rendering on shields.io’s CDN and always shows the latest score. Like Option 2, this only works for public repositories: shields.io fetches the JSON server-side from raw.githubusercontent.com, which cannot read private content. See Private repositories.

​
Private repositories

raw.githubusercontent.com (Option 2) and the shields.io endpoint (Option 3) only render for public repositories. Both hosts serve raw content with no access to private repos, so the badge shows as a broken image. Putting a personal access token in the URL is insecure and against GitHub’s terms, so avoid that. For a private repo, commit the badge into the repository and reference it with a relative link. GitHub renders relative image links for any viewer with read access to the repo: 
![fallow health](.github/badges/health.svg)
To keep it fresh from CI, regenerate the badge and commit it back to a tracked path on your default branch instead of publishing to a separate badges branch: 
- name: Update health badge
  run: |
    fallow health --format badge > .github/badges/health.svg
    git config user.name "github-actions[bot]"
    git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
    git add .github/badges/health.svg
    git diff --quiet --cached || git commit -m "chore: update health badge [skip ci]"
    git push
The job needs permissions: contents: write. A relative link resolves against the branch the README is viewed on, so the badge has to live on that branch: a separate orphan badges branch (Option 2) cannot be reached by a relative link, which is why private repos commit the badge directly.

​
Monorepo badges

For workspace packages, scope the badge with --workspace: 
fallow health --format badge --workspace my-package > badges/my-package.svg

​
Technical details

  • Self-contained SVG with embedded Verdana font metrics. No external requests
  • Unique element IDs per badge, so you can inline multiple badges on one page
  • --format badge automatically enables --score (no need to pass both)
  • Exit code 2 with an error message if the score cannot be computed
  • Also available via the FALLOW_FORMAT=badge environment variable