tracegit

Minimal GitHub Traffic Telemetry System. Sammelt Views, Clones, Pull Requests und Package-Downloads via GitHub API und stellt sie als Dashboard (uPlot) bereit.

Quickstart

Lokal (Go)

export GITHUB_TOKEN=ghp_...
export REPOS=owner/repo,owner/repo2
make run

Podman (empfohlen)

podman-compose up --build

Hinweis: Das Projekt ist auf Podman ausgelegt (rootless). Docker funktioniert ebenfalls, ist aber nicht der primäre Workflow.

GitHub Personal Access Token

Benötigte Scopes für den PAT:

Scope	Zweck
repo	Traffic-Daten (Views, Clones) – erfordert Push-Zugriff auf das Repo
read:packages	Package-Download-Statistiken (optional)

GitHub erlaubt Traffic-Abfragen nur für Repos, auf die der Token-Inhaber Push-Zugriff hat. Für reine Lesezwecke reicht public_repo nicht – repo ist Pflicht.

Environment Variables

Variable	Beschreibung	Default
GITHUB_TOKEN	GitHub PAT (siehe oben)	–
REPOS	Kommagetrennte Repo-Liste (owner/repo)	–
DB_PATH	Pfad zur SQLite-Datenbank	./data/tracegit.db
PORT	HTTP-Port	8855
FETCH_INTERVAL	Abruf-Intervall (Cron-kompatibel, z.B. 6h)	6h

Token und Repos können alternativ über die Web-UI unter /settings konfiguriert werden.

API – Curl-Beispiele

Statistik-Endpunkte

# Views für ein Repo (letzte 7 Tage)
curl "http://localhost:8855/api/views?repo=owner/repo&range=7d"

# Clones für ein Repo (letzte 30 Tage)
curl "http://localhost:8855/api/clones?repo=owner/repo&range=30d"

# Pull Requests
curl "http://localhost:8855/api/pulls?repo=owner/repo&range=7d"

# Package Downloads
curl "http://localhost:8855/api/packages?repo=owner/repo&range=7d"

Repo-Verwaltung

# Gespeicherte Repos auflisten
curl "http://localhost:8855/api/repos"

# Verfügbare GitHub-Repos des Token-Inhabers auflisten
curl "http://localhost:8855/api/github/repos"

Betrieb

# Health Check
curl "http://localhost:8855/health"

# Manuellen Fetch auslösen
curl -X POST "http://localhost:8855/api/fetch"

# Datenbank-Backup herunterladen
curl -o backup.db "http://localhost:8855/api/backup"

# Backup wiederherstellen
curl -X POST "http://localhost:8855/api/restore" \
  -F "file=@backup.db"

CI

Zwei Workflows laufen bei jedem Push/PR auf main:

Workflow	Datei	Was wird geprüft
Build & Test	.github/workflows/build-test.yml	go build, go test, go vet, govulncheck
Container Release	.github/workflows/release-container.yml	Container-Image bauen und pushen

UI

Das Dashboard läuft unter http://localhost:8855/ und zeigt Views, Clones, PRs und Package-Downloads als interaktive uPlot-Graphen. Einstellungen (Token, Repos, Fetch-Intervall) sind über /settings erreichbar.