{"id":51468476,"url":"https://github.com/bulletinmybeard/github-traffic-vault","last_synced_at":"2026-07-06T14:01:21.609Z","repository":{"id":363316435,"uuid":"1262275458","full_name":"bulletinmybeard/github-traffic-vault","owner":"bulletinmybeard","description":"Self-hosted archive for GitHub repo traffic (views, clones, referrers, paths). Keeps the full history GitHub drops after 14 days. SQLite + CLI + web UI.","archived":false,"fork":false,"pushed_at":"2026-07-04T21:44:27.000Z","size":552,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-04T23:12:21.530Z","etag":null,"topics":["cli","data-archival","docker","fastapi","github-api","github-insights","github-traffic","python","repository-analytics","self-hosted","sqlite","traffic-analytics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bulletinmybeard.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T19:47:52.000Z","updated_at":"2026-07-04T21:43:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bulletinmybeard/github-traffic-vault","commit_stats":null,"previous_names":["bulletinmybeard/github-traffic-vault"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/bulletinmybeard/github-traffic-vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fgithub-traffic-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fgithub-traffic-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fgithub-traffic-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fgithub-traffic-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bulletinmybeard","download_url":"https://codeload.github.com/bulletinmybeard/github-traffic-vault/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bulletinmybeard%2Fgithub-traffic-vault/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35193679,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cli","data-archival","docker","fastapi","github-api","github-insights","github-traffic","python","repository-analytics","self-hosted","sqlite","traffic-analytics"],"created_at":"2026-07-06T14:01:20.704Z","updated_at":"2026-07-06T14:01:21.565Z","avatar_url":"https://github.com/bulletinmybeard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Traffic Vault\n\n[![CI](https://github.com/bulletinmybeard/github-traffic-vault/actions/workflows/ci.yml/badge.svg)](https://github.com/bulletinmybeard/github-traffic-vault/actions/workflows/ci.yml)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![Poetry](https://img.shields.io/badge/poetry-managed-blue.svg)](https://python-poetry.org/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Type checking: mypy](https://img.shields.io/badge/type%20checking-mypy-blue.svg)](https://github.com/python/mypy)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nGitHub only retains repository traffic data (views, clones, top referrers, top paths) for about 14 days. **GitHub Traffic Vault** permanently archives that data in SQLite for all of your public repos, so nothing ever gets lost.\n\n\u003ctable\u003e\n  \u003ctr valign=\"top\"\u003e\n    \u003ctd width=\"40%\"\u003e\n      \u003ca href=\".github/assets/github-traffic-vault-index-demo.png\"\u003e\n        \u003cimg width=\"100%\" alt=\"Index page: every public repo as a tile with window and today view/clone totals\" src=\".github/assets/github-traffic-vault-index-demo.png\"\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"40%\"\u003e\n      \u003ca href=\".github/assets/github-traffic-vault-detail-demo.png\"\u003e\n        \u003cimg width=\"100%\" alt=\"Detail page: per-repo daily views/clones chart with CI, release, and open-PR status\" src=\".github/assets/github-traffic-vault-detail-demo.png\"\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"20%\"\u003e\n      \u003ca href=\".github/assets/github-traffic-vault-date-picker.png\"\u003e\n        \u003cimg width=\"100%\" alt=\"Date-range picker: presets plus a custom from/to range\" src=\".github/assets/github-traffic-vault-date-picker.png\"\u003e\n      \u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cem\u003eAll your repos at a glance\u003c/em\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cem\u003ePer-repo history and status\u003c/em\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cem\u003ePick any time window\u003c/em\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## What it does\n\n- **Archives traffic forever**: views, clones, top referrers, top paths — the stuff GitHub only keeps for ~14 days. Stored locally in SQLite, under your control\n- **Syncs your public repos**: discovers everything you own, pulls fresh numbers, and remembers the history. Hit **Sync Now** in the browser or schedule `sync` from the terminal\n- **Shows the big picture**: an index page with every repo as a card — totals for the period you pick, plus today. Defaults to the last 30 days\n- **Drills into one repo**: daily chart, month-by-month breakdown, and a quick status glance (CI, latest release, open PRs)\n- **Flexible date ranges**: same picker on index and detail — this month, last month, last N months, all time, or a custom from/to range\n\nYou need a [GitHub personal access token](https://github.com/settings/tokens) with `repo` scope.\n\n**Option A — `.env` file** (works everywhere). Copy `.env.example` to `.env` and set `GITHUB_TOKEN`.\n\n**Option B — GitHub CLI** (Mac/Linux shortcut). If `gh auth login` already worked for you, leave `.env` empty and the app will borrow that token.\n\nRequires Python 3.12 and [Poetry](https://python-poetry.org/).\n\n```bash\npoetry install\npoetry run github-traffic-vault sync\n```\n\n## CLI\n\n```bash\ngithub-traffic-vault sync                          # discover + sync (cron entry point)\ngithub-traffic-vault sync --only owner/repo        # restrict to specific repos\ngithub-traffic-vault sync --dry-run                # hit the API, roll back DB\n\ngithub-traffic-vault repos                         # list known repos\ngithub-traffic-vault show \u003crepo\u003e [--since DATE]    # daily table + latest top lists\n\ngithub-traffic-vault export \u003crepo|all\u003e [--format csv|json] [--kind views|clones|referrers|paths]\ngithub-traffic-vault top [--by views|clones] [--since DATE] [--limit N]\n\ngithub-traffic-vault serve [--host 127.0.0.1] [--port 8800] [--reload]\n```\n\n## Web UI\n\n```bash\npoetry run github-traffic-vault serve\n# open http://127.0.0.1:8800\n```\n\nThe SPA, server-rendered (FastAPI + Jinja2). Each repo gets a card\nshowing 14-day totals and a per-day breakdown grouped by month.\nThe `Sync Now` button kicks off a real sync (blocks ~7s, then re-renders).\nThe same data is available as JSON at `/api/repos.json`.\n\nWith `--reload`, you enable `uvicorn` auto-reload for dev (or run via Docker with hot-reload, see below).\n\n## Docker\n\nA `Dockerfile` and a compose file for local dev with hot-reload.\n\n### Mac dev (hot-reload)\n\n```bash\ncp .env.example .env\n# set GITHUB_TOKEN, or leave empty to use gh auth token inside the container\n\ndocker compose up --build\n```\n\nUI at [http://127.0.0.1:8800](http://127.0.0.1:8800). Source is bind-mounted with hot-reload, so edits to the code show up without rebuilding.\n\nSync manually from another terminal:\n\n```bash\ndocker compose exec github-traffic-vault github-traffic-vault sync\n```\n\n## Terminal commands\n\nThe web UI covers most of what I need. If you prefer the command line:\n\n| Command | What it does |\n|---------|-------------|\n| `github-traffic-vault sync` | Discover repos and pull traffic data |\n| `github-traffic-vault repos` | List what's in the vault |\n| `github-traffic-vault show \u003cowner/repo\u003e` | Daily table for one repo |\n| `github-traffic-vault export` | Dump one repo or everything as CSV or JSON |\n| `github-traffic-vault top` | Rank repos by views or clones |\n| `github-traffic-vault serve` | Start the web UI |\n\nRun `github-traffic-vault --help` for flags (`--since`, `--only`, `--dry-run`, etc.).\n\n## Where the data lives\n\nEverything lands in a `data/` folder next to where you run the app:\n\n```\ndata/\n├── github-traffic-vault.db\n└── github-traffic-vault.log\n```\n\nBack up `github-traffic-vault.db` and you're good. Open it with any SQLite client if you're curious.\n\n## A few honest limits\n\n- One GitHub account, public repos only\n- The web UI listens on `127.0.0.1` with no login. Fine for local use\n- No test suite yet as it's a personal tool that still grows its legs\n\n## License\n\nMIT, see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletinmybeard%2Fgithub-traffic-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbulletinmybeard%2Fgithub-traffic-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbulletinmybeard%2Fgithub-traffic-vault/lists"}