https://github.com/djdarcy/github-traffic-tracker
Zero-server GitHub traffic analytics with daily collection via Actions, gist-backed storage, and client-side dashboard. GHTraf tracks clones, views, stars, forks, and referrers beyond GitHub's 14-day API limit.
https://github.com/djdarcy/github-traffic-tracker
analytics badges dashboard gist github-actions github-api github-stats github-traffic statistics traffic-analytics
Last synced: about 2 months ago
JSON representation
Zero-server GitHub traffic analytics with daily collection via Actions, gist-backed storage, and client-side dashboard. GHTraf tracks clones, views, stars, forks, and referrers beyond GitHub's 14-day API limit.
- Host: GitHub
- URL: https://github.com/djdarcy/github-traffic-tracker
- Owner: djdarcy
- License: gpl-3.0
- Created: 2026-02-26T08:04:39.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-02-28T01:32:17.000Z (3 months ago)
- Last Synced: 2026-02-28T03:37:09.164Z (3 months ago)
- Topics: analytics, badges, dashboard, gist, github-actions, github-api, github-stats, github-traffic, statistics, traffic-analytics
- Language: Python
- Homepage:
- Size: 220 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# GitHub Traffic Tracker
[![PyPI][pypi-badge]][pypi-url] [![Release Date][release-date-badge]][release-date-url] [![Python 3.10+][python-badge]][python-url] [![License][license-badge]][license-url] [![GitHub Discussions][discussions-badge]][discussions-url] [![Platform][platform-badge]][platform-url]
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](#current-status) for details.
**Live from this repo's own tracker:**
[![Installs][installs-badge]][installs-url] [![Views][views-badge]][views-url] [![Clones][clones-badge]][clones-url]
## 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
```mermaid
flowchart LR
A["GitHub Actions
daily · 3am UTC"] -->|"clones · views
downloads · stars"| B["Public Gist
state.json + badges"]
A -->|"monthly"| C["Archive Gist
long-term snapshots"]
B -->|"client-side fetch"| D["Dashboard
GitHub Pages"]
B -->|"shields.io endpoint"| E["Badges
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](https://cli.github.com) installed and authenticated, Python 3.10+
### Option A: ghtraf CLI (recommended)
```bash
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](docs/parameters.md) for all options.
### Option B: Standalone script
```bash
# 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
```bash
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](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.
```markdown
[](https://USER.github.io/REPO/stats/#installs)
```
## Live Dashboards
This system is actively running on:
- **[GitHub Traffic Tracker](https://djdarcy.github.io/github-traffic-tracker/stats/)** — This project (dogfooding since day 1)
- **[NCSI Resolver](https://dazzletools.github.io/Windows-No-Internet-Secured-BUGFIX/stats/)** — Origin project (v0.7.12)
- **[ComfyUI Triton & SageAttention](https://dazzleml.github.io/comfyui-triton-and-sageattention-installer/stats/#installs)** — First port (v0.8.3)
## Roadmap
See [ROADMAP.md](ROADMAP.md) or [Issue #1 — Roadmap](https://github.com/djdarcy/github-traffic-tracker/issues/1) 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](https://github.com/djdarcy/github-traffic-tracker/issues/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](CONTRIBUTING.md) for details.
Like the project?
[](https://www.buymeacoffee.com/djdarcy)
## License
Github-Traffic-Tracker (ghtraf), Copyright (C) 2025 Dustin Darcy
This project is licensed under the GNU General Public License v3.0 — see [LICENSE](LICENSE) for details.
[release-date-badge]: https://img.shields.io/github/release-date/djdarcy/github-traffic-tracker?color=darkgreen
[release-date-url]: https://github.com/djdarcy/github-traffic-tracker/releases
[pypi-badge]: https://img.shields.io/pypi/v/github-traffic-tracker?color=darkgreen
[pypi-url]: https://pypi.org/project/github-traffic-tracker/
[installs-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/installs.json
[installs-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#installs
[views-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/views.json
[views-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#views
[clones-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/clones.json
[clones-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#clones
[downloads-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/downloads.json
[downloads-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#installs
[python-badge]: https://img.shields.io/badge/python-3.10+-darkgreen
[python-url]: https://www.python.org/downloads/
[license-badge]: https://img.shields.io/badge/license-GPLv3-darkgreen
[license-url]: https://www.gnu.org/licenses/gpl-3.0
[discussions-badge]: https://img.shields.io/github/discussions/djdarcy/github-traffic-tracker
[discussions-url]: https://github.com/djdarcy/github-traffic-tracker/discussions
[platform-badge]: https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey
[platform-url]: docs/platform-support.md