Nota: El archivo de estado
last-sync.jsonse crea automáticamente en la primera sincronización exitosa. Ignora las advertencias de "archivo faltante" en la primera ejecución.
Sincronización Automática de Portafolio
Sincroniza automáticamente tus repositorios de GitHub con tu sitio web de portafolio.
Flujo de trabajo
Paso 1: Recopilar configuración
Pregunta al usuario:
- Nombre de usuario de GitHub: (por defecto desde la configuración de git)
- Tipo de portafolio:
static(projects-data.js) osupabase(API) - Directorio del portafolio: Ruta al proyecto del portafolio
- Filtros: Excluir repositorios (archivados, forks, nombres específicos)
Paso 2: Obtener repositorios mediante la API de GitHub
GET /users/{username}/repos?per_page=100&sort=updated&direction=desc
Extraer: name, description, html_url, homepage, language, topics, updated_at
Filtrar:
- Forks (a menos que el usuario los incluya)
- Repositorios de perfil (
{username}/{username}) - Repositorios archivados
Paso 3: Detectar cambios
Compara con last-sync.json (almacenado en el directorio de la habilidad).
- Nuevos repositorios: No estaban en la última sincronización → proceso completo
- Repositorios actualizados:
updated_atcambió → volver a capturar captura de pantalla - Repositorios sin cambios: Omitir
Paso 4: Capturar capturas de pantalla
Para repositorios con homepage o URL de despliegue:
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();
Guardar en el directorio de capturas de pantalla del portafolio.
Paso 5: Actualizar los datos del portafolio
Estático (projects-data.js)
{
title: '{repo.name}',
description: 'Auto-generado: {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)
});
Paso 6: Guardar estado de sincronización
{
"lastSync": "2026-05-12T18:30:00Z",
"repos": {
"example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
}
}
Paso 7: Reportar resultados
Sincronización completada:
+ 2 nuevos (Cyberian, Image Enhancer)
+ 1 captura de pantalla capturada
+ 1 actualizado (Portfolio)
- 0 errores
Notas
- Las capturas de pantalla requieren Playwright y una URL válida. Omitir si no hay homepage.
- Nunca cambiar
featured: trueen proyectos existentes — solo el usuario puede promocionar. - Programar mediante cron/GitHub Actions para una sincronización semanal.
Manejo de errores
| Causa | Solución |
|---|---|
| La API de GitHub devuelve 401 No autorizado | No hay token o el token ha expirado. Establece la variable de entorno GITHUB_TOKEN. Genera un nuevo token de acceso personal en github.com/settings/tokens con el ámbito public_repo. |
| Límite de tasa de la API de GitHub excedido (403) | Las solicitudes no autenticadas están limitadas a 60/hora. Autenticadas: 5000/hora. Agrega un token. Si ya estás autenticado, espera el reinicio (comprueba el encabezado X-RateLimit-Reset). |
El repositorio no tiene campo homepage ni URL de despliegue | No se puede capturar una captura de pantalla. Marca el repositorio como "sin vista previa en vivo" en la salida. Usa la URL de GitHub como enlace de respaldo. |
| El navegador Playwright no se inicia | Chromium no está instalado. Ejecuta npx playwright install chromium. En un servidor sin interfaz gráfica, agrega la bandera --no-sandbox: chromium.launch({ headless: true, args: ['--no-sandbox'] }). |
| La URL de la captura de pantalla devuelve 404 o expira después de 15s | La URL de despliegue está desactualizada o el sitio está caído. Omite la captura de pantalla para este repositorio. Registra la URL y el error en un archivo failed-screenshots.json para revisión manual. |
projects-data.js tiene formato personalizado que la generación automática rompería | Una inserción basada en expresiones regulares podría dañar el código escrito a mano. Lee primero el archivo para detectar una estructura no estándar. Si se detecta, agrega un bloque de comentarios con las nuevas entradas y pide al usuario que fusione manualmente. |
| La inserción de la API de Supabase falla con una restricción de clave externa o esquema | El esquema del portafolio podría diferir de la forma de la carga útil generada automáticamente. Lee primero el esquema de la tabla de Supabase. Asigna los campos explícitamente (no con el operador spread). Valida con una POST de prueba que devuelva 200 antes de confirmar. |
last-sync.json está corrupto o editado manualmente | Analiza como JSON en un bloque try-catch. En caso de fallo, renombra a last-sync.json.bak e inicia una sincronización completa desde cero. Advierte al usuario de que se ha perdido la detección incremental. |
Patrones de la API de GitHub
Descubrimiento de repositorios
import requests, os
headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}
# Obtener todos los repositorios (paginados)
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
# Filtrar: solo no forks, no archivados, con descripción
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]
Límite de tasa
- API de GitHub: 5,000 solicitudes/hora (autenticadas). Comprueba el encabezado
X-RateLimit-Remaining. - Para repositorios con 500+ repos: usar solicitudes condicionales (
If-None-Matchcon ETag) - Esperar 1s entre capturas de pantalla (evitar el límite de tasa de GitHub en los activos)
Patrón de captura de pantalla con 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()
Recuperación de errores
- Tiempo de espera en carga de página -> reintentar una vez, omitir si aún falla (marcar en la salida)
- Repositorio privado -> omitir (no se puede capturar sin autenticación)
- La página se bloquea -> capturar el estado de error como captura de pantalla
- Fallo de DNS -> omitir con mensaje de registro
Estrategia de caché
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 # Omitir: sin cambios desde la última sincronización
# ... capturar captura de pantalla, actualizar entrada ...
cache[repo['full_name']] = key
json.dump(cache, open(cache_file, 'w'))
Lista de verificación
- El token de GitHub tiene los ámbitos correctos (repo, read:user) antes de obtener repositorios
- La captura de pantalla solo se ejecuta para repositorios con URLs de homepage válidas (primero una comprobación HEAD)
- El navegador Playwright se cierra en un bloque finally para evitar procesos huérfanos
- Las personalizaciones existentes del portafolio se preservan antes de insertar nuevas entradas
- Modo de prueba disponible para previsualizar cambios sin ejecutarlos
Fuentes
- Documentación de la API REST de GitHub v3 (docs.github.com/en/rest/repos/repos) — listado, filtrado y paginación de repositorios
- Documentación de Playwright (playwright.dev/docs/api/class-playwright) — lanzamiento del navegador sin interfaz gráfica, captura de pantalla y configuración del viewport
- Documentación del cliente JavaScript de Supabase (supabase.com/docs/reference/javascript) — inserción, upsert y patrones de autenticación de la API
- Documentación del módulo
fsde Node.js (nodejs.org/api/fs.html) — lectura/escritura de archivos con renombrado atómico para la seguridad del estado de sincronización - Mejores prácticas para tokens de acceso personal (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — ámbitos, caducidad y almacenamiento seguro
- Programación cron de GitHub Actions (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — patrón de sincronización semanal automatizada
- "Automate the Boring Stuff with Python" de Al Sweigart (No Starch Press, 2ª Edición, 2019) — patrones de confiabilidad de automatización aplicables a tareas de automatización en JavaScript
Anti-patrones
| Patrón | Problema | Solución |
|---|---|---|
| Sincronizar sin verificar personalizaciones existentes | Las entradas generadas automáticamente pueden sobrescribir descripciones de proyectos hechas a mano, banderas destacadas o el orden personalizado establecido por el usuario. | Leer primero el archivo de destino. Detectar una estructura no estándar. Para las entradas con featured: true, preservar todos los campos. Solo agregar o actualizar repositorios nuevos o modificados. |
| Capturar capturas de pantalla para todos los repositorios indiscriminadamente | Los repositorios sin demostraciones en vivo desperdician tiempo de lanzamiento de Playwright (~3s cada uno). Los repositorios con URLs rotas producen capturas de pantalla de error inútiles. | Prefiltrar: solo capturar repositorios donde el campo homepage no esté vacío y devuelva 200 en una solicitud HEAD. |
| Ejecutar la sincronización en una conexión medida o lenta | Clonar o capturar docenas de repositorios puede consumir ancho de banda y tiempo significativos. | Ejecutar en lotes de 10. Agregar una bandera --dry-run que liste lo que cambiaría sin ejecutarlo. |
| Usar la clave anón de Supabase en lugar de la clave service_role para escrituras | La clave anón tiene restricciones de seguridad a nivel de fila que bloquean los upserts. | Usar la clave service_role con precaución. Almacenarla en una variable de entorno, nunca en el código. Agregar políticas RLS a nivel de tabla para la función de sincronización. |
| No limpiar los procesos del navegador Playwright después de la sincronización | Cada chromium.launch() genera un proceso. Los procesos huérfanos acumulan memoria y pueden agotar los recursos del sistema. | Siempre llamar a browser.close() en un bloque finally. Rastrear los navegadores lanzados en un array y forzar el cierre en SIGINT/SIGTERM. |
| Codificar la ruta de datos del portafolio en lugar de leerla desde la configuración | Las rutas cambian entre proyectos. Una ruta codificada falla en el primer uso en una máquina diferente. | Preguntar por el directorio del portafolio en el Paso 1. Derivar la ruta de projects-data.js desde esa base. Almacenar en el estado de sincronización para su reutilización. |