Health badges

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:

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 reliable. Options 2 and 3 render only for public repositories; see Private repositories.

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.

Option 2: Publish from CI (recommended)

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)

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.

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