Repo Stats: die GitHub-Zahlen, die nach 14 Tagen verschwinden

Wer wissen will, ob ein Beitrag vom letzten Monat tatsächlich jemanden auf ein Repository gebracht hat, findet die Antwort bei GitHub nicht mehr: Aufrufe, eindeutige Besucher, Clones und Herkunft werden nach vierzehn Tagen gelöscht. Dazu kommt, dass GitHub den Verkehr nur pro Repository zeigt, ohne Übersicht über mehrere, und die Zahl der Release-Downloads in der Oberfläche gar nicht. Repo Stats sammelt diese Daten und stellt sie auf einem eigenen Dashboard dar.

Ein täglicher Lauf gegen die Löschfrist

Kern ist ein täglicher Sammellauf, der Verkehr, Herkunft und Clones wegschreibt, bevor sie ablaufen. Jeder Lauf liefert das komplette Vierzehn-Tage-Fenster. Fällt der Container für ein paar Tage aus, holt der nächste Lauf nach, was dazwischen liegt – solange der Ausfall unter zwei Wochen bleibt. Stündlich werden zusätzlich die günstigen Zähler aktualisiert: Sterne, Forks, Beobachter und Release-Downloads. Alles landet in einer einzigen SQLite-Datei, ein Backup ist eine Dateikopie. Der Container braucht keine fremden Dienste, nach außen gehen nur Anfragen an die GitHub-API und an die Home-Assistant-Statistik.

Eine Sicht über alle Repositories

Die Übersicht zeigt Sterne, Forks, Beobachter, offene Issues, Release-Downloads, Besucher und Clones über alle verfolgten Repositories. Jede Kachel öffnet eine Aufschlüsselung, aus welchen Repositories die Zahl besteht. Pro Repository gibt es die Details: Mitwirkende, Commits, offene und gemergte Pull Requests, Erfolgsquote und Dauer der CI-Läufe aus GitHub Actions, die meistbesuchten Seiten, Downloads je Release-Datei und die offenen Issues mit Links.

Die Sternkurve reicht bis zum ersten Stern zurück. Sie wird aus den Zeitstempeln der einzelnen Stargazer rekonstruiert, die GitHub festhält, die Historie steht also schon nach dem ersten Lauf bereit. Dafür ist ein zweites Token nötig: GitHub weist fein granulierte Tokens am Stargazer-Endpunkt ab, über REST wie über GraphQL, und anonym gibt es dort nichts. GITHUB_TOKEN_STARS nimmt deshalb ein klassisches Token mit public_repo. Getrennt gehalten braucht das Haupttoken nirgends Schreibrechte; ohne das zweite Token beginnt die Kurve mit dem ersten Sammellauf.

Zahlen mit Beipackzettel

Jede Kachel trägt eine Erklärung, was sie zählt. Das hat einen praktischen Grund: Die Clone-Zahl ist zum großen Teil Maschinenverkehr. Jeder actions/checkout ist für GitHub ein Clone, bei einem Matrix-Build einer pro Job, dazu kommen Bots und Spiegeldienste. Die Kacheln führen deshalb mit der Zahl der unterschiedlichen Besucher und Klonenden und zeigen die Rohzahl klein darunter.

Für Home-Assistant-Integrationen holt Repo Stats außerdem die Installationszahl von analytics.home-assistant.io, aufgeteilt nach Version. Das ist heikler, als es klingt: Home Assistant meldet pro Integrations-Domain, und die Domain gehört allen, die diese Integration ausliefern. Gezählt werden daher nur die Versionen, die aus dem eigenen Repository stammen; die Summe der Domain steht daneben. Ein Eintrag zählt einmal je Integration und nicht für Forks.

Betrieb

git clone https://github.com/sphings79/repostats.git
cd repostats
cp .env.example .env     # Token und Konto eintragen
docker compose up -d

Das Dashboard erreicht man unter http://<host>:8377. Das Image ghcr.io/sphings79/repostats:latest gibt es für amd64 und arm64, auf dem eigenen Host wird nichts kompiliert. Erforderlich sind GITHUB_TOKEN und GITHUB_LOGIN; das Token braucht Lesezugriff auf „Administration“ (das schaltet die Verkehrszahlen frei, und es ist das Recht, das man leicht übersieht), dazu Contents, Issues, Metadata, Pull requests und Actions. Mit einem klassischen Token genügt der Scope repo.

Die Anmeldung wird im Browser eingerichtet und nicht über die Umgebung; in der ersten Fassung kam sie noch aus den Umgebungsvariablen. Beim ersten Start gibt es noch kein Konto, jeder Aufruf landet auf einer Einrichtungsseite. Das sollte man direkt nach docker compose up erledigen: Bis dahin legt das Konto an, wer den Port zuerst erreicht, und im Container liegt ein Token, das auch die privaten Repositories lesen kann. Wer das Passwort vergisst, verwirft das Konto in der Datenbank und richtet es neu ein; der Befehl steht im README. Hinter einem Reverse Proxy zeigt docs/traefik.yaml.example eine Route mit zwei Schlössern, Beschränkung aufs eigene Netz und Anmeldung des Dashboards obendrauf.

Lizenz: MIT, dann AGPL

Version 1.0.1 ändert nur die Lizenz, von MIT auf AGPL-3.0. Die Begründung: Repo Stats läuft als Dienst, und die GPL verlangt Quelltext nur dort, wo Software weitergegeben wird – bei etwas, das man im Browser nutzt, passiert das nie. Die AGPL schließt die Lücke: Wer es anderen über ein Netz anbietet, gibt auch den Quelltext seiner Fassung heraus. Entsprechend verlinkt die Fußzeile jetzt den Quelltext. Wer das Tarball von 1.0.0 gezogen hat, hat noch den MIT-Text vor sich.

Nach den ersten Releases kam noch eine Anzeige hinzu, was sich seit dem letzten Besuch geändert hat, sowie die Info-Knöpfe mit gleich hohen Kacheln. Wer sich dafür interessiert, welche Zahlen noch fehlen: Ich bitte ausdrücklich um Issues und Pull Requests zu fehlenden Auswertungen.