Roadmap · Project hygiene · P3 · S

CI status badge

A build-it-yourself guide. The CI workflow (.github/workflows/ci.yml, testing Python 3.10–3.13) already runs on every push and PR. This surfaces its result as a badge at the top of the README — a cheap, at-a-glance signal of health for anyone evaluating the package.

Done when: a live CI badge sits at the top of the README, links to the workflow's runs, and shows passing green on main.
0 / 0 steps
← roadmap ← changelog + tags ← README install ← single-source version

Prerequisite

This one depends on CI landing first — and it has. GitHub auto-serves a badge SVG for any workflow at a predictable URL built from the repo and the workflow file name:

  1. Owner/repo: IsaiahKoamalu/modulearn
  2. Workflow file: ci.yml (the name: inside is CI — that's the badge's label).
The badge tracks the default branch. By default the SVG reflects the latest run on main. That's what you want at the top of a README — "is main green right now?"

Steps

  1. Add the badge to the top of the README
    README.md — immediately under the # ModuLearn title

    The image links to the workflow's run history so a click goes straight to the logs.

    # ModuLearn

[![CI](https://github.com/IsaiahKoamalu/modulearn/actions/workflows/ci.yml/badge.svg)](https://github.com/IsaiahKoamalu/modulearn/actions/workflows/ci.yml)
    Pin to a branch if you like. Append ?branch=main to the badge.svg URL to make the "reflects main" behavior explicit and immune to anyone running the workflow from a fork branch.
  2. Verify the badge renders and links correctly

    The SVG is public — you can fetch it before pushing to confirm the URL is right, then eyeball it on GitHub after.

    curl -sI "https://github.com/IsaiahKoamalu/modulearn/actions/workflows/ci.yml/badge.svg" \
  | grep -i "content-type"     # expect: image/svg+xml
# after pushing: open the repo on GitHub — badge shows "CI passing" (green)
# click it — lands on the workflow's runs list
    Grey "no status"? That means the workflow file name in the URL doesn't match a real workflow, or it hasn't run on the default branch yet. Confirm the path is exactly ci.yml and that a run exists via gh run list --workflow ci.yml.
  3. Commit
    git add README.md
git commit -m "README: add CI status badge"
git push
gh run list --branch main --limit 1   # expect: success (and the badge follows it)
  4. Mark it shipped on the roadmap

    Add done:true, to the {area:"hygiene", … title:"CI status badge"} item in docs/roadmap.html.

Worth knowing

A badge is only as honest as the suite behind it. A green badge over a thin test suite is false comfort. It pairs best with the Testing work — the more the CI matrix actually covers (the compiler's type rules, server endpoints, the round-trip), the more that green square is worth to a reader deciding whether to trust the package.