{"id":48028447,"url":"https://github.com/djdarcy/github-traffic-tracker","last_synced_at":"2026-04-04T13:53:16.602Z","repository":{"id":341091879,"uuid":"1167363577","full_name":"djdarcy/github-traffic-tracker","owner":"djdarcy","description":"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.","archived":false,"fork":false,"pushed_at":"2026-02-28T01:32:17.000Z","size":225,"stargazers_count":0,"open_issues_count":41,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T03:37:09.164Z","etag":null,"topics":["analytics","badges","dashboard","gist","github-actions","github-api","github-stats","github-traffic","statistics","traffic-analytics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/djdarcy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"djdarcy","ko_fi":"djdarcy","buy_me_a_coffee":"djdarcy"}},"created_at":"2026-02-26T08:04:39.000Z","updated_at":"2026-02-28T01:32:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/djdarcy/github-traffic-tracker","commit_stats":null,"previous_names":["djdarcy/github-traffic-tracker"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/djdarcy/github-traffic-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2Fgithub-traffic-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2Fgithub-traffic-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2Fgithub-traffic-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2Fgithub-traffic-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djdarcy","download_url":"https://codeload.github.com/djdarcy/github-traffic-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2Fgithub-traffic-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","badges","dashboard","gist","github-actions","github-api","github-stats","github-traffic","statistics","traffic-analytics"],"created_at":"2026-04-04T13:53:15.990Z","updated_at":"2026-04-04T13:53:16.593Z","avatar_url":"https://github.com/djdarcy.png","language":"Python","funding_links":["https://github.com/sponsors/djdarcy","https://ko-fi.com/djdarcy","https://buymeacoffee.com/djdarcy","https://www.buymeacoffee.com/djdarcy"],"categories":[],"sub_categories":[],"readme":"# GitHub Traffic Tracker\n\n[![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]\n\nZero-server GitHub traffic analytics — daily collection, permanent history, smart badges.\n\n\u003e **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.\n\n**Live from this repo's own tracker:**\n\n[![Installs][installs-badge]][installs-url] [![Views][views-badge]][views-url] [![Clones][clones-badge]][clones-url]\n\n## The Problem\n\nGitHub'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.\n\nGitHub 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.\n\n## How It Works\n\n```mermaid\nflowchart LR\n    A[\"GitHub Actions\u003cbr/\u003edaily · 3am UTC\"] --\u003e|\"clones · views\u003cbr/\u003edownloads · stars\"| B[\"Public Gist\u003cbr/\u003estate.json + badges\"]\n    A --\u003e|\"monthly\"| C[\"Archive Gist\u003cbr/\u003elong-term snapshots\"]\n    B --\u003e|\"client-side fetch\"| D[\"Dashboard\u003cbr/\u003eGitHub Pages\"]\n    B --\u003e|\"shields.io endpoint\"| E[\"Badges\u003cbr/\u003eREADME / anywhere\"]\n```\n\nA 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.\n\n## Features\n\n- **Daily data collection** — Clones, views, downloads, stars, forks, referrers, popular paths\n- **Permanent history** — Accumulates beyond the 14-day API window indefinitely\n- **Unique visitor tracking** — Unique cloners and viewers alongside raw counts\n- **CI clone detection** — Separates organic clones from CI/CD checkout noise\n- **Cascading recency badges** — `installs 1,234 (+18 24h)` → `(+88 wk)` → `(+145 mo)`\n- **Tabbed dashboard** — Overview, Installs, Views, Community, Dev tabs\n- **Monthly archives** — Long-term snapshots in a separate unlisted Gist\n- **Zero server** — Pure GitHub Actions + Gist storage + client-side rendering\n\n## Quick Start\n\n**Prerequisites:** [gh CLI](https://cli.github.com) installed and authenticated, Python 3.10+\n\n### Option A: ghtraf CLI (recommended)\n\n```bash\npip install github-traffic-tracker\nghtraf create --owner YOUR_ORG --repo YOUR_REPO --configure --repo-dir /path/to/your/repo\n```\n\nTo redeploy templates without cloud setup (e.g., after upgrading ghtraf), use `ghtraf create --files-only`.\nSee [docs/parameters.md](docs/parameters.md) for all options.\n\n### Option B: Standalone script\n\n```bash\n# Interactive — prompts for all values\npython setup-gists.py\n\n# Or fully automated\npython setup-gists.py --owner YOUR_ORG --repo YOUR_REPO --configure\n\n# Preview without making changes\npython setup-gists.py --dry-run\n```\n\nBoth options will:\n1. Create a public badge Gist and an unlisted archive Gist\n2. Set repository variables (`TRAFFIC_GIST_ID`, `TRAFFIC_ARCHIVE_GIST_ID`)\n3. Guide you through creating a PAT with `gist` scope\n4. Optionally configure the dashboard and workflow files (`--configure`)\n\nAfter setup, enable GitHub Pages (Settings \u003e Pages \u003e Deploy from branch \u003e main, /docs) and push.\n\n## Verbosity \u0026 Diagnostics\n\n```bash\nghtraf -v create ...              # Level 1 — setup steps, API calls, gist operations\nghtraf -vv create ...             # Level 2 — config detail, gist IDs\nghtraf -QQ create ...             # Quieter — warnings and errors only\nghtraf --show gist:2 create ...   # Show only gist channel at level 2\nghtraf --show                     # List all available channels\n```\n\nEight named channels (`api`, `config`, `gist`, `setup`, `general`, `hint`, `error`, `trace`) let you see specific diagnostics without global noise.\n\nFor full parameter documentation, see [docs/parameters.md](docs/parameters.md).\n\n## Badge Showcase\n\n| Badge | What it shows | Example |\n|-------|--------------|---------|\n| **Installs** | Downloads + clones combined, with cascading recency | `installs 1,234 (+18 24h)` |\n| **Views** | Repository page views with recency | `views 5,678 (+92 24h)` |\n| **Clones** | Git clones (organic, excluding CI) | `clones 890 (+7 24h)` |\n| **Downloads** | Release asset downloads | `downloads 456` |\n\nRecency 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.\n\n```markdown\n[![Installs](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/USER/GIST_ID/raw/installs.json)](https://USER.github.io/REPO/stats/#installs)\n```\n\n## Live Dashboards\n\nThis system is actively running on:\n\n- **[GitHub Traffic Tracker](https://djdarcy.github.io/github-traffic-tracker/stats/)** — This project (dogfooding since day 1)\n- **[NCSI Resolver](https://dazzletools.github.io/Windows-No-Internet-Secured-BUGFIX/stats/)** — Origin project (v0.7.12)\n- **[ComfyUI Triton \u0026 SageAttention](https://dazzleml.github.io/comfyui-triton-and-sageattention-installer/stats/#installs)** — First port (v0.8.3)\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) or [Issue #1 — Roadmap](https://github.com/djdarcy/github-traffic-tracker/issues/1) for the full plan.\n\n## Current Status\n\nGTT 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.\n\n**What works today:**\n\n- Daily traffic collection via GitHub Actions\n- Permanent history in Gist storage (beyond GitHub's 14-day window)\n- Cascading recency badges (installs, views, clones)\n- 5-tab dashboard with charts\n- `setup-gists.py` onboarding script\n- `pip install github-traffic-tracker` / `pip install ghtraf`\n- Structured verbosity (`-v`/`-Q`/`--show`) with 8 named output channels\n- `ghtraf create --files-only` — copy workflow + dashboard templates into your repo\n\n**In progress:**\n\n- `ghtraf` CLI subcommands: `status`, `list`, `verify` ([#6](https://github.com/djdarcy/github-traffic-tracker/issues/6))\n- Schema migration tooling (`ghtraf upgrade`)\n\n**Known limitations:**\n\n- CI clone subtraction uses heuristic formulas (empirical validation planned)\n- Dashboard is a single HTML file (JS modularization planned)\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.\n\nLike the project?\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/djdarcy)\n\n## License\n\nGithub-Traffic-Tracker (ghtraf), Copyright (C) 2025 Dustin Darcy \n\nThis project is licensed under the GNU General Public License v3.0 — see [LICENSE](LICENSE) for details.\n\n\u003c!-- Badge references --\u003e\n\n[release-date-badge]: https://img.shields.io/github/release-date/djdarcy/github-traffic-tracker?color=darkgreen\n[release-date-url]: https://github.com/djdarcy/github-traffic-tracker/releases\n[pypi-badge]: https://img.shields.io/pypi/v/github-traffic-tracker?color=darkgreen\n[pypi-url]: https://pypi.org/project/github-traffic-tracker/\n[installs-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/installs.json\n[installs-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#installs\n[views-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/views.json\n[views-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#views\n[clones-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/clones.json\n[clones-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#clones\n[downloads-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/downloads.json\n[downloads-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#installs\n[python-badge]: https://img.shields.io/badge/python-3.10+-darkgreen\n[python-url]: https://www.python.org/downloads/\n[license-badge]: https://img.shields.io/badge/license-GPLv3-darkgreen\n[license-url]: https://www.gnu.org/licenses/gpl-3.0\n[discussions-badge]: https://img.shields.io/github/discussions/djdarcy/github-traffic-tracker\n[discussions-url]: https://github.com/djdarcy/github-traffic-tracker/discussions\n[platform-badge]: https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey\n[platform-url]: docs/platform-support.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjdarcy%2Fgithub-traffic-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjdarcy%2Fgithub-traffic-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjdarcy%2Fgithub-traffic-tracker/lists"}