Note : Le fichier d'état
last-sync.jsonest 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) ousupabase(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_ata 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: truesur les projets existants — seul l'utilisateur peut promouvoir. - Planifier via cron/GitHub Actions pour une synchronisation hebdomadaire.
Gestion des erreurs
| Cause | Correctif |
|---|---|
| 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éploiement | Impossible 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 pas | Chromium 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 15s | L'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 casser | Une 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éma | Le 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é manuellement | Analyser 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-Matchavec 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
fsde 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
| Patron | Problème | Correctif |
|---|---|---|
| Synchroniser sans vérifier les personnalisations existantes | Les 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 discernement | Les 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 lente | Le 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 écritures | La 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 synchronisation | Chaque 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 configuration | Les 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. |