github-traffic-tracker · PyPI
Skip to main content github-traffic-tracker 0.3.11 Zero-server GitHub traffic analytics — daily collection via Actions, gist-backed storage, client-side dashboard pip install github-traffic-tracker 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: Create a public badge Gist and an unlisted archive Gist Set repository variables ( TRAFFIC_GIST_ID , TRAFFIC_ARCHIVE_GIST_ID ) Guide you through creating a PAT with gist scope 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 Badge What it shows Example Installs Downloads + clones combined, with cascading recency installs 1,234 (+18 24h) Views Repository page views with recency views 5,678 (+92 24h) Clones Git clones (organic, excluding CI) clones 890 (+7 24h) Downloads Release asset downloads downloads 456 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. [ ](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. Project links Data verified by PyPI on Jun 24, 2026 Data provided by the project maintainers, verified at the time the release was uploaded to PyPI. Dashboard Homepage Issues Repository Key dates PyPI data Data sourced directly from PyPI's database.
Released: Jun 24, 2026 Latest release 1 maintainer PyPI data Data sourced directly from PyPI's database. djdarcy Credits Author: Dustin GitHub Statistics Data verified by PyPI on Jun 24, 2026 The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified. Repository Stars: Forks: Open issues: Open PRs: Provenance Data verified by PyPI on Jun 24, 2026 Data provided by the project maintainers and verified by PyPI at the time of upload.
Full provenance Both files in this release have provenance metadata. View provenance details License expression GPL-3.0-or-later View SPDX License List Requires Python >=3.10 Provides Extra dev Tags github traffic analytics badges gist actions dashboard clones views stars Classifiers Development Status 3 - Alpha Environment Console Intended Audience Developers Operating System OS Independent Programming Language Python :: 3 Python :: 3.10 Python :: 3.11 Python :: 3.12 Topic Software Development :: Version Control :: Git Metadata Project links Data verified by PyPI on Jun 24, 2026 Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.
Dashboard Homepage Issues Repository Key dates PyPI data Data sourced directly from PyPI's database. Released: Jun 24, 2026 Latest release 1 maintainer PyPI data Data sourced directly from PyPI's database. djdarcy Credits Author: Dustin GitHub Statistics Data verified by PyPI on Jun 24, 2026 The GitHub source repository
The rest of this page is on the live site.