https://github.com/bulletinmybeard/github-traffic-vault
Self-hosted archive for GitHub repo traffic (views, clones, referrers, paths). Keeps the full history GitHub drops after 14 days. SQLite + CLI + web UI.
https://github.com/bulletinmybeard/github-traffic-vault
cli data-archival docker fastapi github-api github-insights github-traffic python repository-analytics self-hosted sqlite traffic-analytics
Last synced: about 3 hours ago
JSON representation
Self-hosted archive for GitHub repo traffic (views, clones, referrers, paths). Keeps the full history GitHub drops after 14 days. SQLite + CLI + web UI.
- Host: GitHub
- URL: https://github.com/bulletinmybeard/github-traffic-vault
- Owner: bulletinmybeard
- License: mit
- Created: 2026-06-07T19:47:52.000Z (29 days ago)
- Default Branch: master
- Last Pushed: 2026-07-04T21:44:27.000Z (2 days ago)
- Last Synced: 2026-07-04T23:12:21.530Z (1 day ago)
- Topics: cli, data-archival, docker, fastapi, github-api, github-insights, github-traffic, python, repository-analytics, self-hosted, sqlite, traffic-analytics
- Language: Python
- Homepage:
- Size: 539 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Traffic Vault
[](https://github.com/bulletinmybeard/github-traffic-vault/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](https://python-poetry.org/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/python/mypy)
[](LICENSE)
GitHub 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.
All your repos at a glance
Per-repo history and status
Pick any time window
## What it does
- **Archives traffic forever**: views, clones, top referrers, top paths — the stuff GitHub only keeps for ~14 days. Stored locally in SQLite, under your control
- **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
- **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
- **Drills into one repo**: daily chart, month-by-month breakdown, and a quick status glance (CI, latest release, open PRs)
- **Flexible date ranges**: same picker on index and detail — this month, last month, last N months, all time, or a custom from/to range
You need a [GitHub personal access token](https://github.com/settings/tokens) with `repo` scope.
**Option A — `.env` file** (works everywhere). Copy `.env.example` to `.env` and set `GITHUB_TOKEN`.
**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.
Requires Python 3.12 and [Poetry](https://python-poetry.org/).
```bash
poetry install
poetry run github-traffic-vault sync
```
## CLI
```bash
github-traffic-vault sync # discover + sync (cron entry point)
github-traffic-vault sync --only owner/repo # restrict to specific repos
github-traffic-vault sync --dry-run # hit the API, roll back DB
github-traffic-vault repos # list known repos
github-traffic-vault show [--since DATE] # daily table + latest top lists
github-traffic-vault export [--format csv|json] [--kind views|clones|referrers|paths]
github-traffic-vault top [--by views|clones] [--since DATE] [--limit N]
github-traffic-vault serve [--host 127.0.0.1] [--port 8800] [--reload]
```
## Web UI
```bash
poetry run github-traffic-vault serve
# open http://127.0.0.1:8800
```
The SPA, server-rendered (FastAPI + Jinja2). Each repo gets a card
showing 14-day totals and a per-day breakdown grouped by month.
The `Sync Now` button kicks off a real sync (blocks ~7s, then re-renders).
The same data is available as JSON at `/api/repos.json`.
With `--reload`, you enable `uvicorn` auto-reload for dev (or run via Docker with hot-reload, see below).
## Docker
A `Dockerfile` and a compose file for local dev with hot-reload.
### Mac dev (hot-reload)
```bash
cp .env.example .env
# set GITHUB_TOKEN, or leave empty to use gh auth token inside the container
docker compose up --build
```
UI 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.
Sync manually from another terminal:
```bash
docker compose exec github-traffic-vault github-traffic-vault sync
```
## Terminal commands
The web UI covers most of what I need. If you prefer the command line:
| Command | What it does |
|---------|-------------|
| `github-traffic-vault sync` | Discover repos and pull traffic data |
| `github-traffic-vault repos` | List what's in the vault |
| `github-traffic-vault show ` | Daily table for one repo |
| `github-traffic-vault export` | Dump one repo or everything as CSV or JSON |
| `github-traffic-vault top` | Rank repos by views or clones |
| `github-traffic-vault serve` | Start the web UI |
Run `github-traffic-vault --help` for flags (`--since`, `--only`, `--dry-run`, etc.).
## Where the data lives
Everything lands in a `data/` folder next to where you run the app:
```
data/
├── github-traffic-vault.db
└── github-traffic-vault.log
```
Back up `github-traffic-vault.db` and you're good. Open it with any SQLite client if you're curious.
## A few honest limits
- One GitHub account, public repos only
- The web UI listens on `127.0.0.1` with no login. Fine for local use
- No test suite yet as it's a personal tool that still grows its legs
## License
MIT, see [LICENSE](LICENSE).