Your README Deserves Real Numbers

Alberto Arena — Fri, 05 Jun 2026 07:21:44 +0000

If you maintain an open-source repo, you have probably wondered at some point how many people actually visit it. GitHub has the answer buried in the Insights tab, but nobody looks there. It resets after 14 days, there is no history, and your README, the thing everyone sees, tells them nothing.

I built traffic-badge to fix that.

What it does

It is a GitHub Action that runs on a schedule, hits the official GitHub Traffic API, and commits a live SVG badge to a dedicated branch in your repo. You embed that badge in your README once and it updates automatically from then on.

The badge shows whatever you care about: total views, unique visitors, clones, unique cloners. One workflow file per metric, or stack them all.

Why it is different from the alternatives

A lot of traffic badge solutions rely on a third-party counting server. Which means you are trusting someone else's infrastructure, someone else's uptime, and someone else's definition of "a view." When that server goes down or changes its counting logic, your badge quietly becomes wrong.

traffic-badge does not phone home. The numbers come straight from GitHub's own API, the same data you would see in your Insights tab. The raw JSON is committed to your repo under a traffic-data branch, so you can inspect every data point, diff it, delete it, whatever you want. Full transparency.

It also handles the awkward overlap problem. GitHub's Traffic API returns a rolling 14-day window, so if you run the action daily you would normally double-count the days that appear in both runs. traffic-badge deduplicates by date automatically, so your cumulative totals stay accurate without any extra work on your end.

Setting it up

First, a heads-up that saves you the most common mistake: the default GITHUB_TOKEN does not work here. The Traffic API requires push or admin access, which that token does not have, so it fails with 403 Resource not accessible by integration. You need a Personal Access Token instead: a classic PAT with the repo scope, or a fine-grained PAT with Administration: read on the repo. Add it as a repository secret called TRAFFIC_TOKEN.

Then add a workflow file:

name: Traffic Badge
on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

permissions:
  contents: write

jobs:
  badge:
    runs-on: ubuntu-latest
    steps:
      - uses: albertoarena/github-traffic-badge@v1
        with:
          token: ${{ secrets.TRAFFIC_TOKEN }}
          metric: views
          color: blue

Run it once manually, then grab the badge URL it creates and drop it in your README:

![Views](https://raw.githubusercontent.com/OWNER/REPO/traffic-data/badge.svg)

That is it. No server to maintain, no API key for a third-party service, no monthly bill. It runs on free GitHub-hosted runners.

The options worth knowing

The metric field accepts views, clones, views-unique, and clones-unique. You can run multiple workflows with different metrics if you want to show both.

color takes any named colour or a hex value. style supports the standard shields.io styles: flat, flat-square, plastic, for-the-badge. And if your numbers get large enough that the badge looks cluttered, there is an abbreviated flag that turns 12345 into 12.3K.

A note on how it is built

If you like to read the code before trusting an Action with a PAT, it is worth a look. Zero runtime dependencies, Node 20+ with built-in fetch and the built-in test runner. The counting and rendering logic is written as pure functions with the network, filesystem, and clock injected, so it is fully tested without touching disk or hitting the API. The zero-dependency constraint is enforced in CI.