Inicio rápido

Seis pasos y un fichero de configuración. La única decisión que merece pensarse antes de empezar es qué almacén guarda la historia, y se puede aplazar imprimiendo primero los puntos por la terminal.

El camino corto

Si tienes una terminal, deja que pregunte:

ghchronicle -setup

Pide un token, le pregunta a GitHub de quién es, pregunta qué cuenta recoger y dónde poner los números, comprueba que ese sitio responde, ofrece el dashboard y ofrece dejarlo funcionando solo. Lo que escribe es un config.yaml que carga y, si pediste servicio, una unidad, un agente o una tarea programada según el sistema.

Las credenciales nunca van en la configuración. Van a un fichero al lado que solo puedes leer tú, y la configuración las nombra.

El instalador de arriba lo ofrece como último paso, así que en una máquina nueva los dos juntos son todo lo que hay que hacer.

El resto de esta página es lo que escribe, para quien prefiera escribirlo a mano o quiera saber a qué acaba de decir que sí.

De cero a la primera pasada

1. Instala el binario.

   Script

   curl -fsSL https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.sh | bash

   En Windows, desde PowerShell:

   irm https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.ps1 | iex

   Release

   Coge el archivo de tu plataforma en la página de releases y pon ghchronicle en el PATH.

   Contenedor

   docker pull ghcr.io/jmrplens/ghchronicle

   Go

   go install github.com/jmrplens/ghchronicle/v2/cmd/ghchronicle@latest

2. Crea un token en https://github.com/settings/tokens y expórtalo.

   export GITHUB_TOKEN=github_pat_...

   Un token clásico con repo, read:packages, read:user, read:org, security_events, read:public_key y read:gpg_key ve todo lo que esto recoge. La página del token explica qué permiso compra qué familia, y por qué el GITHUB_TOKEN automático de una Action no basta.

3. Escribe la configuración. Dos decisiones, y este es el fichero entero:

   config.yaml

   github:
     token: ${GITHUB_TOKEN}
   targets:
     user: tu-login
   sinks:
     stdout: true # cámbialo por influxdb cuando tengas dónde guardarlo

   Un ${VAR} en una credencial, una dirección o una ruta de fichero se lee del entorno al arrancar, así que el fichero no contiene secretos y se puede versionar. Todo lo demás tiene un valor por omisión.

   La versión documentada, la que comenta todas las opciones que hay, vive en el repositorio y no en la instalación, así que cógela de ahí cuando quieras leer el resto:

   curl -O https://raw.githubusercontent.com/jmrplens/ghchronicle/main/config.example.yaml

4. Mira qué se recogería, antes de gastar cuota en ello.

   ghchronicle -config config.yaml -list

   Eso imprime los repositorios en alcance. Los forks y los archivados quedan fuera por omisión. Si falta algo que esperabas, esta es la orden que te lo dice.

5. Ejecuta una pasada.

   ghchronicle -config config.yaml -once

   Con sinks.stdout: true los puntos salen por la terminal como line protocol en vez de ir a una base de datos, que es la forma más barata de ver la forma de lo que estás a punto de guardar.

6. Déjalo corriendo.

   ghchronicle -config config.yaml

   Cada familia corre entonces con su propia cadencia: las ejecuciones de workflows cada quince minutos, el calendario de contribuciones cada hora, las claves SSH y GPG de la cuenta una vez al día.

Qué hace la primera pasada que las siguientes no hacen

Cuatro cosas ocurren una sola vez, y son la razón de que la primera pasada sea la cara.

• Se lee el historial diario de estrellas de cada repositorio, vea lo que vea el token, hasta la primera semana del repositorio, y se recorre entera, página a página, la lista de estrellas de cada repositorio cuya lista el token puede leer (desde julio de 2026, solo los administradores y colaboradores del repositorio), para que cada una de esas estrellas lleve el momento en que se dio y quién la dio. Después, el historial es una petición por repositorio por sus treinta semanas más nuevas, casi siempre un 304 gratis, y las cien estrellas más nuevas de cada lista legible viajan en una consulta GraphQL por cada diez repositorios.
• Un mes de ejecuciones de workflows, para que una instalación nueva no dibuje una historia de CI que empieza hace quince minutos. Después, el doble de la cadencia, y nunca menos de dos horas.
• Las pull requests en coautoría de toda la vida de la cuenta, que achievements recorre para el recuento de Pair Extraordinaire: 35 consultas y 23,7 MB sobre 2.315 pull requests fusionadas, medido el 2026-09-27. Después, una pasada recorre los días desde entonces, una página, y el historial entero otra vez una vez por semana.
• El calendario de contribuciones de cada año, si every.families.history está puesto, hasta el día en que se creó la cuenta. Después, solo el año en curso, reescrito a su cadencia.

Tampoco hay nada en caché todavía, así que cada respuesta de la primera pasada se paga entera, donde una posterior pregunta con el ETag con que llegó la última respuesta y casi siempre recibe un 304 gratis; ver la caché que hay junto al fichero de estado.

Espera unos pocos miles de puntos de una primera pasada sobre veinte repositorios, y unos pocos cientos de cada una de las siguientes.

Nada de eso es la historia. La primera pasada es un incremento más ancho, y un dashboard a noventa días o a dos años empieza entonces el día en que instalaste el colector: medido tras un día de pasadas, alrededor de una quinta parte de las pull requests que declaran los repositorios, commits solo de los últimos treinta días y jobs de una décima parte de las ejecuciones de workflows. Lanza ghchronicle -config config.yaml -backfill una vez, antes del servicio o justo después; la página del relleno dice hasta dónde llega y lo que cuesta.

Conserva el fichero de estado

state_file es lo que recuerda por dónde iba cada familia, y dentro viven nueve cosas. Bórralo y la siguiente pasada lo recoge todo otra vez, lo que cuesta cuota y nada más en siete de las nueve. Las otras dos son el commit desde el que arranca cada diff de dependencias, cuyos cambios del hueco no se vuelven a recoger, y lo que el fichero registra de cada almacén, entre ello una relectura que una migración aún debe, que entonces nada vuelve a leer.

Por dónde seguir

• Formas de instalar es lo que convierte la orden de arriba en algo que sigue corriendo: systemd, Docker o una Action programada.
• La fecha del punto es la idea de diseño de la que se deriva todo lo demás.
• Elegir almacén decide qué preguntas podrás hacer después.
• Coste de una pasada es el precio medido en llamadas a la API.