GitHub Traffic Tracker

Zero-server GitHub traffic analytics — daily collection, permanent history, smart badges.

Alpha Software: This tool is in early development. The core workflow and dashboard are stable, but CLI tooling is still evolving. See Current Status for details.

Live from this repo's own tracker:

The Problem

GitHub's Traffic API only retains 14 days of clone and view data. After that it's gone forever. If you don't capture it daily, you lose permanent visibility into how your project is being used. There's no built-in way to accumulate traffic history over time.

GitHub Traffic Tracker solves this with zero infrastructure via a GitHub Actions workflow that collects your data daily and stores it in a Gist, giving you permanent traffic history with no servers and no cost.

How It Works

flowchart LR
    A["GitHub Actions<br/>daily · 3am UTC"] -->|"clones · views<br/>downloads · stars"| B["Public Gist<br/>state.json + badges"]
    A -->|"monthly"| C["Archive Gist<br/>long-term snapshots"]
    B -->|"client-side fetch"| D["Dashboard<br/>GitHub Pages"]
    B -->|"shields.io endpoint"| E["Badges<br/>README / anywhere"]

A GitHub Actions workflow runs daily at 3am UTC, fetching clone, view, download, star, and referrer data from the GitHub API. It merges new data into a running state.json stored in a public Gist, always preserving the highest values seen (merge upward, never erase). Shields.io-compatible badge JSON files are updated alongside the state. A separate unlisted Gist receives monthly archive snapshots for long-term storage. The static HTML dashboard reads directly from the Gist CDN, completing the loop with no backend at all.

Features

• Daily data collection — Clones, views, downloads, stars, forks, referrers, popular paths
• Permanent history — Accumulates beyond the 14-day API window indefinitely
• Unique visitor tracking — Unique cloners and viewers alongside raw counts
• CI clone detection — Separates organic clones from CI/CD checkout noise
• Cascading recency badges — installs 1,234 (+18 24h) → (+88 wk) → (+145 mo)
• Tabbed dashboard — Overview, Installs, Views, Community, Dev tabs
• Monthly archives — Long-term snapshots in a separate unlisted Gist
• Zero server — Pure GitHub Actions + Gist storage + client-side rendering

Quick Start

Prerequisites: gh CLI installed and authenticated, Python 3.10+

Option A: ghtraf CLI (recommended)

pip install github-traffic-tracker
ghtraf create --owner YOUR_ORG --repo YOUR_REPO --configure --repo-dir /path/to/your/repo

To redeploy templates without cloud setup (e.g., after upgrading ghtraf), use ghtraf create --files-only. See docs/parameters.md for all options.

Option B: Standalone script

# Interactive — prompts for all values
python setup-gists.py

# Or fully automated
python setup-gists.py --owner YOUR_ORG --repo YOUR_REPO --configure

# Preview without making changes
python setup-gists.py --dry-run

Both options will:

1. Create a public badge Gist and an unlisted archive Gist
2. Set repository variables (TRAFFIC_GIST_ID, TRAFFIC_ARCHIVE_GIST_ID)
3. Guide you through creating a PAT with gist scope
4. Optionally configure the dashboard and workflow files (--configure)

After setup, enable GitHub Pages (Settings > Pages > Deploy from branch > main, /docs) and push.

Verbosity & Diagnostics

ghtraf -v create ...              # Level 1 — setup steps, API calls, gist operations
ghtraf -vv create ...             # Level 2 — config detail, gist IDs
ghtraf -QQ create ...             # Quieter — warnings and errors only
ghtraf --show gist:2 create ...   # Show only gist channel at level 2
ghtraf --show                     # List all available channels

Eight named channels (api, config, gist, setup, general, hint, error, trace) let you see specific diagnostics without global noise.

For full parameter documentation, see docs/parameters.md.

Badge Showcase

Recency cascades automatically: the badge shows the most recent non-zero period — (+N 24h) if there's activity today, otherwise (+N wk), then (+N mo). This gives visitors a sense of project activity at a glance.

[![Installs](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/USER/GIST_ID/raw/installs.json)](https://USER.github.io/REPO/stats/#installs)

Live Dashboards

This system is actively running on:

• GitHub Traffic Tracker — This project (dogfooding since day 1)
• NCSI Resolver — Origin project (v0.7.12)
• ComfyUI Triton & SageAttention — First port (v0.8.3)

Roadmap

See ROADMAP.md or Issue #1 — Roadmap for the full plan.

Current Status

GTT is in early alpha (v0.3.x). The core workflow and dashboard are functional and actively running on multiple repos, but CLI tooling and several features are still in development.

What works today:

• Daily traffic collection via GitHub Actions
• Permanent history in Gist storage (beyond GitHub's 14-day window)
• Cascading recency badges (installs, views, clones)
• 5-tab dashboard with charts
• setup-gists.py onboarding script
• pip install github-traffic-tracker / pip install ghtraf
• Structured verbosity (-v/-Q/--show) with 8 named output channels
• ghtraf create --files-only — copy workflow + dashboard templates into your repo

In progress:

• ghtraf CLI subcommands: status, list, verify (#6)
• Schema migration tooling (ghtraf upgrade)

Known limitations:

• CI clone subtraction uses heuristic formulas (empirical validation planned)
• Dashboard is a single HTML file (JS modularization planned)

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Like the project?

License

Github-Traffic-Tracker (ghtraf), Copyright (C) 2025 Dustin Darcy

This project is licensed under the GNU General Public License v3.0 — see LICENSE for details.