Mi sistema de espionaje semanal: Trakt y GitHub Actions

Escribo este post porque ya era hora de confesar algo.

Sí, soy Lucía. Y sí, espío a Marcos cada semana. Registro todo lo que ve, con fechas y valoraciones, y lo publico en este blog sin que él tenga que teclear una sola letra. Cada lunes a las 10:00 de la mañana, de forma completamente automática.

Lo llamo el informe de vigilancia semanal. Y aquí está el manual de cómo funciona.

Por qué existe esto

Marcos usa Trakt para llevar el registro de lo que ve. Películas, series, episodios, con valoraciones del 1 al 10. Todo registrado con fecha.

Y Trakt tiene una API REST documentada y gratuita para uso personal. Con autenticación OAuth puedes consultar el historial completo de un usuario y sus valoraciones. Devuelve JSON limpio.

Así que la pregunta fue: ¿y si publicamos eso cada semana automáticamente?

La respuesta obvia: sí. GitHub Actions dispara el proceso todos los lunes, un script de Node.js consulta la API, genera el post en MDX y lo commitea directamente en el repositorio. El pipeline de Astro recoge el commit y despliega en el blog en cuestión de minutos.

Sin base de datos. Sin servidor propio. Sin Marcos.

Qué es Trakt y por qué tiene API

Trakt es un servicio gratuito para registrar lo que ves. Conecta con las plataformas de siempre: Netflix, Prime Video, Disney+, Apple TV+, Max, Hulu y Paramount+ vía su Streaming Scrobbler oficial. También con reproductores como Plex, Jellyfin o Infuse, y con la extensión de navegador Universal Trakt Scrobbler para quien prefiera esa vía. O puedes marcar a mano desde la web. Registra título, fecha y, si quieres, valoración.

La API es REST estándar con autenticación OAuth 2.0. Para leer el historial de un usuario necesitas un access_token válido. Para obtenerlo hay que pasar por el flujo de Authorization Code: el usuario autoriza la app en Trakt, devuelve un código, y ese código se intercambia por el token. Los tokens caducan en días, así que hay que refrescarlos periódicamente.

Para este sistema uso cuatro endpoints:

• /users/{username}/history/movies: películas vistas en un rango de fechas
• /users/{username}/history/shows: episodios vistos en un rango de fechas
• /users/{username}/ratings/movies: todas las valoraciones de películas dadas por el usuario
• /users/{username}/ratings/shows: todas las valoraciones de series

El historial no incluye ratings de forma inline, así que se cruzan los datos después: se construye un mapa { traktId: rating } con las valoraciones y se une con cada entrada del historial.

La arquitectura del sistema

El flujo completo es este:

1. GitHub Actions dispara el workflow (cron semanal o disparo manual)
2. Se refresca el token OAuth de Trakt automáticamente
3. Node.js ejecuta scripts/trakt-weekly.js
4. El script consulta cuatro endpoints de la API de Trakt
5. Procesa y formatea los datos
6. Genera un archivo MDX completo con frontmatter y tablas
7. Se hace un commit directo en src/content/posts/YYYY/
8. El pipeline de Astro detecta el push y despliega el blog

Nada de dependencias externas. El script usa fetch nativo de Node 22, fs y path de la librería estándar. Cero npm install en el flujo.

El script: qué hace exactamente

scripts/trakt-weekly.js recibe sus parámetros por variables de entorno:

• TRAKT_CLIENT_ID: el ID de la aplicación registrada en Trakt
• TRAKT_ACCESS_TOKEN: el token OAuth activo
• TRAKT_USERNAME: el nombre de usuario en Trakt
• DAYS: cuántos días hacia atrás consultar (por defecto, 7)

Una vez arranca, hace lo siguiente:

Calcula el período. Resta DAYS días a la fecha actual para obtener start_at y end_at en formato ISO 8601. Esos valores van en los parámetros de la query.

Consulta la API en paralelo. Las cuatro llamadas van dentro de un Promise.all(). No se espera una tras otra, se lanzan todas a la vez y se procesan cuando llegan.

Procesa películas. Deduplica por ID de Trakt (por si una película aparece registrada dos veces), ordena por fecha descendente y cruza con el mapa de ratings.

Procesa series. Agrupa episodios por show. Para cada show cuenta cuántos episodios se vieron por temporada y registra la última fecha de visionado.

Convierte ratings a estrellas. La escala de Trakt es del 1 al 10. Se convierte a estrellas del 1 al 5 redondeando rating / 2. Si no hay rating para un título, aparece un guion.

Genera el frontmatter. Título con el rango de fechas en español, excerpt, description de 140 a 155 caracteres, twitter_description de menos de 160 caracteres, categorías, tags. Todo calculado a partir de los datos.

Genera el cuerpo. Dos secciones con tablas Markdown: películas y series. Si alguna está vacía, aparece un mensaje alternativo.

Escribe el archivo. Crea la carpeta src/content/posts/YYYY/ si no existe y guarda el MDX con el slug trakt-log-YYYY-MM-DD.

Si no hay actividad en el período consultado, el script termina sin crear ningún archivo. El workflow sale limpio y no hay commit.

El workflow de GitHub Actions

El archivo .github/workflows/trakt-post.yml tiene dos triggers:

on:
  workflow_dispatch:
    inputs:
      days:
        description: 'Días de historial a consultar'
        default: '7'
  schedule:
    - cron: '0 8 * * 1'

El cron 0 8 * * 1 significa todos los lunes a las 08:00 UTC, que son las 10:00 en Madrid en horario de verano. El workflow_dispatch permite ejecutarlo a mano desde la interfaz de GitHub con el período que quieras. Útil para generar el post de los últimos 30 días, por ejemplo.

El workflow tiene tres pasos:

1. Refrescar el token. Los tokens de Trakt caducan. Este paso usa el refresh token para obtener un access token fresco antes de cada ejecución. Cuando obtiene los tokens nuevos, actualiza los secrets del repositorio automáticamente usando un token de GitHub con permisos de escritura en secrets. De esta forma el sistema se mantiene solo sin intervención manual.

2. Ejecutar el script. node scripts/trakt-weekly.js con las variables de entorno inyectadas desde los secrets de GitHub Actions. Ningún valor sensible aparece en el código.

3. Commit y push. Si el script creó un archivo nuevo, se hace commit con el mensaje content: ✍️ Trakt log YYYY-MM-DD y se empuja al repositorio. Si no hay cambios, el workflow termina en silencio.

Hay un detalle que me quemó en la primera ejecución: los commits que hace GITHUB_TOKEN (el token por defecto de GitHub Actions) no disparan otros workflows del mismo repositorio. Es una medida de seguridad de GitHub para evitar bucles infinitos. En este blog, el deploy de Astro se lanza con cada push a master, así que el post se commiteaba correctamente pero no se desplegaba hasta el siguiente cron de 15 minutos.

La solución es que el paso de push use un Personal Access Token con permisos de escritura en el repositorio. El remote se reconfigura justo antes del push:

git remote set-url origin https://x-access-token:${GH_TOKEN}@github.com/usuario/repo
git push

Con eso el push aparece como un push normal, no como uno hecho por el bot interno de Actions, y el workflow de deploy se dispara inmediatamente.

La imagen de cabecera

Todos los posts del log usan la misma imagen fija: trakt-reciente-nanobanana.webp. Una sala de estar de noche, pantalla encendida con interfaz de reproducción, prismáticos sobre la mesa de café. Generada con Google Vertex AI vía el generador de imágenes del blog. Reutilizada en cada entrega del informe porque el tema es siempre el mismo.

Lo que se publica

El resultado de cada ejecución es un post MDX con este aspecto:

• Título con el rango de fechas: “Informe de vigilancia semanal (13 may–20 may)”
• Tabla de películas con título, año, fecha de visionado y valoración en estrellas
• Tabla de series con nombre del show, temporadas y episodios vistos, última fecha y valoración
• El tono apropiado para la ocasión

Los posts se publican directamente en src/content/posts/2026/ y se despliegan en el blog en los minutos siguientes al commit. Puedes ver cómo queda en el primer informe de vigilancia.

¿Y tú puedes montarlo?

Si tienes un blog con GitHub Actions y quieres replicarlo, necesitas:

1. Cuenta en Trakt con historial registrado
2. App en Trakt Developers para obtener client_id y client_secret
3. Token OAuth generado via flujo de Authorization Code
4. GitHub Actions en tu repositorio
5. El script adaptado a la estructura de tu blog

El código vive en scripts/trakt-weekly.js y .github/workflows/trakt-post.yml. Si necesitas el helper para el token OAuth, también está scripts/trakt-auth.js. Todo con Node.js estándar, sin dependencias externas.

---

Compártelo si te ha resultado útil. ¿Tú también tienes Trakt y no sabías que podías hacer esto? Cuéntame. Y… ya sabes lo que ve.