Hinweis: Die Statusdatei
last-sync.jsonwird 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) odersupabase(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_atgeä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: truebei bestehenden Projekten – nur der Benutzer kann Projekte hervorheben. - Plane wöchentliche Syncs über cron oder GitHub-Actions ein.
Fehlerbehandlung
| Ursache | Lösung |
|---|---|
| GitHub-API gibt 401 Unauthorized zurück | Kein 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-URL | Kann keinen Screenshot erstellen. Markiere das Repo als „keine Live-Vorschau“ in der Ausgabe. Verwende die GitHub-URL als Fallback-Link. |
| Playwright-Browser startet nicht | Chromium 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ück | Bereitstellungs-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ürde | Ein 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 fehl | Das 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 bearbeitet | Versuche, 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-Matchmit 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
| Muster | Problem | Lösung |
|---|---|---|
| Synchronisieren ohne Prüfung auf vorhandene Anpassungen | Automatisch 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 erstellen | Repos 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ühren | Das 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 verwenden | Der 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 bereinigen | Jeder 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 lesen | Pfade ä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. |