Communitygithub.com

EliasOulkadi/shokunin

Automatische Synchronisation von GitHub-Repos mit deiner Portfolio-Website. Scannt Repos, erstellt Screenshots mit Playwright, generiert Projekteinträge und aktualisiert die projects-data.js oder Supabase-Datenbank.

Was ist shokunin?

Diese Fähigkeit synchronisiert automatisch GitHub-Repositories mit einer Portfolio-Website. Sie ruft alle öffentlichen Repos eines Benutzers über die GitHub-API ab, filtert irrelevante (z. B. Forks, archivierte Repos) und erkennt Änderungen durch einen Vergleich mit einer lokalen Cache-Datei (`last-sync.json`). Für jedes neue oder aktualisierte Repository mit einer gültigen Startseiten-URL wird mithilfe von Playwright ein Screenshot erstellt. Die Projektdaten werden dann entweder in eine statische `projects-data.js`-Datei oder über die Supabase-API in die Datenbank eingefügt. Der gesamte Prozess ist als Batch-Sync konzipiert, beachtet die Ratenlimits der GitHub-API und enthält Wiederholungslogik für fehlgeschlagene Screenshots. Die Fähigkeit unterstützt sowohl statische (JS-Datei) als auch dynamische (Supabase) Portfolios und bietet eine trockene Testlaufoption zur Vorschau der Änderungen, ohne sie tatsächlich durchzuführen.

Funktioniert mit~Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add https://github.com/EliasOulkadi/shokunin/tree/HEAD/.pack/skills/portfolio-auto

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Hinweis: Die Statusdatei last-sync.json wird beim ersten erfolgreichen Sync automatisch erstellt. Ignoriere Warnungen zu „fehlender Datei“ beim ersten Ausführen.

Portfolio-Auto-Sync

Automatisch GitHub-Repositories mit deiner Portfolio-Website synchronisieren.

Arbeitsablauf

Schritt 1: Konfiguration sammeln

Frage den Benutzer nach:

  • GitHub-Benutzername: (Standard aus der Git-Konfiguration)
  • Portfolio-Typ: static (projects-data.js) oder supabase (API)
  • Portfolio-Verzeichnis: Pfad zum Portfolio-Projekt
  • Filter: Auszuschließende Repos (archivierte Repos, Forks, bestimmte Namen)

Schritt 2: Repos über GitHub-API abrufen

GET /users/{username}/repos?per_page=100&sort=updated&direction=desc

Extrahiere: name, description, html_url, homepage, language, topics, updated_at

Filtere heraus:

  • Forks (außer der Benutzer stimmt zu)
  • Profil-Repos ({username}/{username})
  • Archivierte Repos

Schritt 3: Änderungen erkennen

Vergleiche mit last-sync.json (im Skill-Verzeichnis gespeichert).

  • Neue Repos: Nicht im letzten Sync → vollständige Verarbeitung
  • Aktualisierte Repos: updated_at geändert → neuen Screenshot erstellen
  • Unveränderte Repos: Überspringen

Schritt 4: Screenshots erstellen

Für Repos mit einer homepage oder Bereitstellungs-URL:

const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.URL, { waitUntil: 'networkidle', timeout: 15000 });
await page.screenshot({ path: `/tmp/portfolio-${name}.png`, fullPage: false });
await browser.close();

Speichern im Screenshot-Verzeichnis des Portfolios.

Schritt 5: Portfolio-Daten aktualisieren

Statisch (projects-data.js)

{
  title: '{repo.name}',
  description: 'Auto-generated: {description}',
  tech: '{language},{topics}',
  github_url: '{html_url}',
  live_url: '{homepage || ""}',
  featured: false
}

Supabase

const res = await fetch('https://your-site.com/api/projects', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' },
  body: JSON.stringify(projectData)
});

Schritt 6: Sync-Status speichern

{
  "lastSync": "2026-05-12T18:30:00Z",
  "repos": {
    "example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
  }
}

Schritt 7: Ergebnisse melden

Sync abgeschlossen:
+ 2 neue (Cyberian, Image Enhancer)
+ 1 Screenshot erstellt
+ 1 aktualisiert (Portfolio)
- 0 Fehler

Hinweise

  • Screenshots erfordern Playwright + eine gültige URL. Überspringe, wenn keine Startseite vorhanden ist.
  • Ändere niemals featured: true bei bestehenden Projekten – nur der Benutzer kann Projekte hervorheben.
  • Plane wöchentliche Syncs über cron oder GitHub-Actions ein.

Fehlerbehandlung

UrsacheLösung
GitHub-API gibt 401 Unauthorized zurückKein Token oder Token abgelaufen. Setze die Umgebungsvariable GITHUB_TOKEN. Erstelle ein neues Personal Access Token auf github.com/settings/tokens mit dem Bereich public_repo.
Ratenlimit der GitHub-API überschritten (403)Nicht authentifizierte Anfragen sind auf 60/Stunde begrenzt. Authentifiziert: 5000/Stunde. Füge Token hinzu. Falls bereits authentifiziert, warte auf Reset (überprüfe den X-RateLimit-Reset-Header).
Repository hat kein homepage-Feld und keine Bereitstellungs-URLKann keinen Screenshot erstellen. Markiere das Repo als „keine Live-Vorschau“ in der Ausgabe. Verwende die GitHub-URL als Fallback-Link.
Playwright-Browser startet nichtChromium nicht installiert. Führe npx playwright install chromium aus. Auf einem headless Server füge das --no-sandbox-Flag hinzu: chromium.launch({ headless: true, args: ['--no-sandbox'] }).
Screenshot-URL gibt 404 oder Timeout nach 15s zurückBereitstellungs-URL ist veraltet oder die Seite ist nicht erreichbar. Überspringe den Screenshot für dieses Repo. Protokolliere die URL und den Fehler in einer failed-screenshots.json-Datei zur manuellen Überprüfung.
projects-data.js hat benutzerdefinierte Formatierung, die die Auto-Generierung zerstören würdeEin regex-basiertes Einfügen könnte handgeschriebenen Code beschädigen. Lies die Datei zuerst, um nicht standardmäßige Strukturen zu erkennen. Falls erkannt, füge einen Kommentarblock mit den neuen Einträgen an und bitte den Benutzer, diese manuell einzufügen.
Supabase-API-Insert schlägt wegen Fremdschlüssel- oder Schema-Constraint fehlDas Portfolio-Schema könnte von der automatisch generierten Nutzlast abweichen. Lies zuerst das Supabase-Tabellenschema. Ordne Felder explizit zu (nicht den Spread-Operator verwenden). Validiere mit einem Trockenlauf-POST, der 200 zurückgibt, bevor du ausführst.
last-sync.json ist beschädigt oder manuell bearbeitetVersuche, es als JSON zu parsen (try-catch). Bei Fehler benenne es in last-sync.json.bak um und starte einen vollständigen Sync von Grund auf. Warne den Benutzer, dass die inkrementelle Erkennung verloren geht.

GitHub-API-Muster

Repository-Erkennung

import requests, os

headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}

# Alle Repos abrufen (paginiert)
repos = []
page = 1
while True:
    r = requests.get(f"https://api.github.com/user/repos?per_page=100&page={page}&sort=updated", headers=headers)
    batch = r.json()
    if not batch: break
    repos.extend(batch)
    page += 1

# Filtern: nur nicht-forks, nicht-archivierte, mit Beschreibung
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]

Ratenbegrenzung

  • GitHub-API: 5.000 Anfragen/Stunde (authentifiziert). Überprüfe den X-RateLimit-Remaining-Header.
  • Für Repos mit 500+ Repos: verwende bedingte Anfragen (If-None-Match mit ETag)
  • Warte 1s zwischen Screenshot-Erstellungen (um das Ratenlimit von GitHub für Assets zu vermeiden)

Playwright-Screenshot-Muster

from playwright.sync_api import sync_playwright

def capture(url, output_path):
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={"width": 1280, "height": 800})
        page.goto(url, timeout=15000, wait_until="networkidle")
        page.screenshot(path=output_path, full_page=False)
        browser.close()

Fehlerbehebung

  • Timeout beim Laden der Seite → einmal wiederholen, bei erneutem Fehler überspringen (in Ausgabe markieren)
  • Privates Repo → überspringen (kann ohne Authentifizierung keinen Screenshot erstellen)
  • Seitenabsturz → Fehlerzustand als Screenshot erfassen
  • DNS-Fehler → überspringen mit Protokollmeldung

Caching-Strategie

import hashlib, json, os
cache_file = ".sync-cache.json"
cache = json.load(open(cache_file)) if os.path.exists(cache_file) else {}

for repo in repos:
    key = hashlib.md5(f"{repo['full_name']}:{repo['pushed_at']}".encode()).hexdigest()
    if cache.get(repo['full_name']) == key:
        continue  # Überspringen: keine Änderungen seit letztem Sync
    # ... Screenshot erfassen, Eintrag aktualisieren ...
    cache[repo['full_name']] = key

json.dump(cache, open(cache_file, 'w'))

Checkliste

  • GitHub-Token hat die richtigen Bereiche (repo, read:user) vor dem Abrufen der Repos
  • Screenshot wird nur für Repos mit gültigen Startseiten-URLs ausgeführt (zuerst HEAD-Prüfung)
  • Playwright-Browser wird im finally-Block geschlossen, um verwaiste Prozesse zu verhindern
  • Bestehende Portfolio-Anpassungen bleiben erhalten, bevor neue Einträge eingefügt werden
  • Trockenlauf-Modus verfügbar, um Änderungen ohne Ausführung zu sehen

Quellen

  • GitHub REST API v3-Dokumentation (docs.github.com/en/rest/repos/repos) — Repository-Auflistung, Filterung und Paginierung
  • Playwright-Dokumentation (playwright.dev/docs/api/class-playwright) — Headless-Browserstart, Screenshot und Viewport-Konfiguration
  • Supabase JavaScript-Client-Dokumentation (supabase.com/docs/reference/javascript) — API-Insert, Upsert und Authentifizierungsmuster
  • Node.js fs-Modul-Dokumentation (nodejs.org/api/fs.html) — Datei-Lesen/Schreiben mit atomarer Umbenennung für Sync-Status-Sicherheit
  • Best Practices für Personal Access Tokens (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — Bereiche, Ablauf und sichere Speicherung
  • GitHub Actions cron-Planung (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — Muster für wöchentliche Sync-Automatisierung
  • „Automate the Boring Stuff with Python“ von Al Sweigart (No Starch Press, 2. Auflage, 2019) — Muster für Automatisierungszuverlässigkeit, anwendbar auf JavaScript-Automatisierungsaufgaben

Anti-Patterns

MusterProblemLösung
Synchronisieren ohne Prüfung auf vorhandene AnpassungenAutomatisch generierte Einträge könnten handgeschriebene Projektbeschreibungen, Hervorhebungsflags oder benutzerdefinierte Reihenfolgen überschreiben.Lies zuerst die Zieldatei. Erkenne nicht standardmäßige Strukturen. Bei featured: true-Einträgen alle Felder erhalten. Füge nur neue oder geänderte Repos ein (Upsert).
Screenshots für jedes Repo ohne Unterschied erstellenRepos ohne Live-Demos verschwenden Playwright-Startzeit (~3s pro Repo). Repos mit defekten URLs erzeugen nutzlose Fehler-Screenshots.Vorfiltern: nur Repos mit nicht leerem homepage-Feld, das bei HEAD-Anfrage 200 zurückgibt.
Sync bei einer gemessenen oder langsamen Verbindung ausführenDas Klonen oder Erstellen von Screenshots für Dutzende Repos kann erhebliche Bandbreite und Zeit verbrauchen.Führe in Batches von 10 aus. Füge ein --dry-run-Flag hinzu, das nur auflistet, was sich ändern würde, ohne es auszuführen.
Den Supabase-Anon-Key anstelle des service_role-Keys für Schreibzugriffe verwendenDer Anon-Key unterliegt Einschränkungen auf Zeilenebene, die Upserts blockieren.Verwende den service_role-Key mit Vorsicht. Speichere in der Umgebungsvariable, niemals im Code. Füge RLS-Richtlinien auf Tabellenebene für die Sync-Funktion hinzu.
Playwright-Browser-Prozesse nach dem Sync nicht bereinigenJeder chromium.launch() startet einen Prozess. Verwaiste Prozesse sammeln Speicher an und können Systemressourcen erschöpfen.Rufe immer browser.close() in einem finally-Block auf. Verfolge gestartete Browser in einem Array und erzwinge das Schließen bei SIGINT/SIGTERM.
Den Portfolio-Datenpfad fest codieren, anstatt aus der Konfiguration zu lesenPfade ändern sich zwischen Projekten. Ein fest codierter Pfad schlägt bei der ersten Verwendung auf einem anderen Rechner fehl.Frage in Schritt 1 nach dem Portfolio-Verzeichnis. Leite den projects-data.js-Pfad von diesem Basisverzeichnis ab. Speichere in der Sync-Statusdatei zur Wiederverwendung.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Verwandte Skills