Communitygithub.com

Portfolio Auto-Sync

Synchronise automatiquement les dépôts GitHub vers votre site portfolio. Capture des captures d'écran via Playwright, génère des entrées de projet et met à jour projects-data.js ou Supabase.

Qu'est-ce que Portfolio Auto-Sync ?

Cette compétence automatisée (skill) est conçue pour synchroniser en masse les dépôts GitHub publics ou privés d'un développeur vers son site portfolio statique ou basé sur Supabase. Elle fonctionne en deux phases principales : d'abord, elle interroge l'API GitHub pour récupérer la liste des dépôts, les filtrer (exclure forks, archivés, profils) et détecter les changements par rapport à une synchronisation précédente (fichier last-sync.json). Ensuite, pour chaque dépôt nouveau ou mis à jour, elle utilise Playwright en mode headless pour capturer une capture d'écran de la page d'accueil ou de l'URL de déploiement. Les données extraites (nom, description, langage, topics) sont formatées et insérées soit directement dans un fichier projects-data.js (portfolio statique), soit via l'API Supabase. La compétence gère les erreurs courantes (limites de taux API, Playwright non installé, URLs cassées) et propose des stratégies de cache et de reprise. Elle évite les anti-patrons comme l'écrasement de personnalisations ou les processus Playwright orphelins. Utile pour maintenir un portfolio à jour automatiquement, idéalement via cron ou GitHub Actions.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Note : Le fichier d'état last-sync.json est créé automatiquement lors de la première synchronisation réussie. Ignorez les avertissements de « fichier manquant » lors de la première exécution.

Que fait Portfolio Auto-Sync ?

Synchronise automatiquement les dépôts GitHub vers votre site portfolio.

Workflow

Étape 1 : Rassembler la configuration

Demandez à l'utilisateur :

  • Nom d'utilisateur GitHub : (par défaut depuis git config)
  • Type de portfolio : static (projects-data.js) ou supabase (API)
  • Répertoire du portfolio : Chemin vers le projet portfolio
  • Filtres : Exclure les dépôts (archivés, forks, noms spécifiques)

Étape 2 : Récupérer les dépôts via l'API GitHub

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

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

Filtrer :

  • Forks (sauf si l'utilisateur choisit de les inclure)
  • Dépôts de profil ({username}/{username})
  • Dépôts archivés

Étape 3 : Détecter les changements

Comparez avec last-sync.json (stocké dans le répertoire de la compétence).

  • Nouveaux dépôts : Pas dans la dernière synchronisation → processus complet
  • Dépôts mis à jour : updated_at a changé → recapture d'écran
  • Dépôts inchangés : Ignorer

Étape 4 : Capturer des captures d'écran

Pour les dépôts ayant un champ homepage ou une URL de déploiement :

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();

Sauvegarder dans le répertoire de captures d'écran du portfolio.

Étape 5 : Mettre à jour les données du portfolio

Statique (projects-data.js)

{
  title: '{repo.name}',
  description: 'Généré automatiquement : {description}',
  tech: '{language},{topics}',
  github_url: '{html_url}',
  live_url: '{homepage || ""}',
  featured: false
}

Supabase

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

Étape 6 : Sauvegarder l'état de synchronisation

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

Étape 7 : Rapporter les résultats

Synchronisation terminée :
+ 2 nouveaux (Cyberian, Image Enhancer)
+ 1 capture d'écran effectuée
+ 1 mis à jour (Portfolio)
- 0 erreurs

Remarques

  • Les captures d'écran nécessitent Playwright + une URL valide. Ignorer si pas de page d'accueil.
  • Ne jamais modifier featured: true sur les projets existants — seul l'utilisateur peut promouvoir.
  • Planifier via cron/GitHub Actions pour une synchronisation hebdomadaire.

Gestion des erreurs

CauseCorrectif
L'API GitHub renvoie 401 Non autoriséPas de jeton ou jeton expiré. Définir la variable d'environnement GITHUB_TOKEN. Générer un nouveau jeton d'accès personnel sur github.com/settings/tokens avec le scope public_repo.
Limite de débit API GitHub dépassée (403)Les requêtes non authentifiées sont limitées à 60/heure. Authentifiées : 5000/heure. Ajouter un jeton. Si déjà authentifié, attendre la réinitialisation (vérifier l'en-tête X-RateLimit-Reset).
Le dépôt n'a pas de champ homepage ni d'URL de déploiementImpossible de capturer une capture d'écran. Marquer le dépôt comme « pas d'aperçu en direct » dans la sortie. Utiliser l'URL GitHub comme lien de repli.
Le navigateur Playwright ne démarre pasChromium non installé. Exécuter npx playwright install chromium. Sur un serveur sans tête, ajouter le flag --no-sandbox : chromium.launch({ headless: true, args: ['--no-sandbox'] }).
L'URL de capture d'écran renvoie 404 ou expire après 15sL'URL de déploiement est obsolète ou le site est hors service. Ignorer la capture d'écran pour ce dépôt. Enregistrer l'URL et l'erreur dans un fichier failed-screenshots.json pour examen manuel.
projects-data.js a un format personnalisé que l'auto-génération pourrait casserUne insertion basée sur une regex pourrait corrompre du code écrit à la main. Lire d'abord le fichier pour détecter une structure non standard. Si détecté, ajouter un bloc de commentaires avec les nouvelles entrées et demander à l'utilisateur de fusionner manuellement.
L'insertion dans l'API Supabase échoue avec une contrainte de clé étrangère ou de schémaLe schéma du portfolio pourrait différer de la forme de la charge utile générée automatiquement. Lire d'abord le schéma de la table Supabase. Mapper les champs explicitement (pas d'opérateur spread). Valider avec un POST à sec qui renvoie 200 avant de valider.
last-sync.json est corrompu ou modifié manuellementAnalyser comme JSON dans un try-catch. En cas d'échec, renommer en last-sync.json.bak et recommencer une synchronisation complète depuis le début. Avertir l'utilisateur que la détection incrémentielle est perdue.

Modèles d'API GitHub

Découverte de dépôts

import requests, os

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

# Récupérer tous les dépôts (paginated)
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

# Filtrer : seulement les non-forks, non-archivés, avec description
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]

Limitation de débit

  • API GitHub : 5 000 requêtes/heure (authentifié). Vérifier l'en-tête X-RateLimit-Remaining.
  • Pour les dépôts avec 500+ dépôts : utiliser des requêtes conditionnelles (If-None-Match avec ETag)
  • Attendre 1s entre les captures d'écran (éviter la limite de débit GitHub sur les ressources)

Modèle de capture d'écran Playwright

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()

Récupération d'erreur

  • Délai d'attente du chargement de la page → réessayer une fois, ignorer si échec persistant (marquer dans la sortie)
  • Dépôt privé → ignorer (impossible de capturer une capture d'écran sans authentification)
  • Plantage de la page → capturer l'état d'erreur comme capture d'écran
  • Échec DNS → ignorer avec message de journal

Stratégie de cache

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  # Ignorer : aucun changement depuis la dernière synchronisation
    # ... capturer capture d'écran, mettre à jour l'entrée ...
    cache[repo['full_name']] = key

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

Liste de vérification

  • Le jeton GitHub a les scopes corrects (repo, read:user) avant de récupérer les dépôts
  • La capture d'écran ne s'exécute que pour les dépôts avec URLs homepage valides (vérifier HEAD d'abord)
  • Le navigateur Playwright est fermé dans un bloc finally pour éviter les processus orphelins
  • Les personnalisations existantes du portfolio sont préservées avant d'ajouter ou de mettre à jour les nouvelles entrées
  • Mode simulation disponible pour prévisualiser les changements sans exécuter

Sources

  • Documentation de l'API REST GitHub v3 (docs.github.com/fr/rest/repos/repos) — liste, filtrage et pagination des dépôts
  • Documentation Playwright (playwright.dev/docs/api/class-playwright) — lancement du navigateur sans tête, capture d'écran et configuration de la zone d'affichage
  • Documentation du client JavaScript Supabase (supabase.com/docs/reference/javascript) — insertion, upsert et modèles d'authentification via l'API
  • Documentation du module fs de Node.js (nodejs.org/api/fs.html) — lecture/écriture de fichier avec renommage atomique pour la sécurité de l'état de synchronisation
  • Bonnes pratiques pour les jetons d'accès personnels (docs.github.com/fr/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — scopes, expiration et stockage sécurisé
  • Planification cron GitHub Actions (docs.github.com/fr/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — modèle d'automatisation de synchronisation hebdomadaire
  • « Automate the Boring Stuff with Python » par Al Sweigart (No Starch Press, 2e édition, 2019) — modèles de fiabilité d'automatisation applicables aux tâches d'automatisation JavaScript

Anti-patrons

PatronProblèmeCorrectif
Synchroniser sans vérifier les personnalisations existantesLes entrées générées automatiquement peuvent écraser les descriptions de projet, les indicateurs 'featured' ou l'ordre personnalisé défini par l'utilisateur.Lire d'abord le fichier cible. Détecter une structure non standard. Pour les entrées featured: true, préserver tous les champs. N'ajouter ou mettre à jour que les dépôts nouveaux ou modifiés.
Capturer des captures d'écran pour chaque dépôt sans discernementLes dépôts sans démos en direct gaspillent du temps de lancement Playwright (~3s chacun). Les dépôts avec URLs cassées produisent des captures d'écran d'erreur inutiles.Pré-filtrer : ne capturer que les dépôts où le champ homepage est non vide et renvoie 200 sur une requête HEAD.
Exécuter la synchronisation sur une connexion limitée ou lenteLe clonage ou la capture d'écran de dizaines de dépôts peut consommer une bande passante et du temps importants.Exécuter par lots de 10. Ajouter un flag --dry-run qui liste ce qui changerait sans exécuter.
Utiliser la clé anon Supabase au lieu de la clé service_role pour les écrituresLa clé anon a des restrictions de sécurité au niveau des lignes qui bloquent les upserts.Utiliser la clé service_role avec précaution. Stocker dans une variable d'environnement, jamais dans le code. Ajouter des politiques RLS au niveau de la table pour la fonction de synchronisation.
Ne pas nettoyer les processus navigateur Playwright après la synchronisationChaque chromium.launch() crée un processus. Les processus orphelins accumulent la mémoire et peuvent épuiser les ressources système.Toujours appeler browser.close() dans un bloc finally. Suivre les navigateurs lancés dans un tableau et forcer la fermeture sur SIGINT/SIGTERM.
Coder en dur le chemin des données du portfolio au lieu de lire depuis la configurationLes chemins changent entre les projets. Un chemin codé en dur échoue dès la première utilisation sur une machine différente.Demander le répertoire du portfolio à l'étape 1. Dériver le chemin projects-data.js à partir de cette base. Stocker dans l'état de synchronisation pour réutilisation.

Individual skills in this repo

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

Skills associés