Ir al contenido
ghchronicle

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.

De cero a la primera pasada

Sección titulada «De cero a la primera pasada»

  1. Instala el binario.

    Ventana de terminal
    go install github.com/jmrplens/ghchronicle/cmd/ghchronicle@latest

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

    Ventana de terminal
    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

    Cada ${VAR} 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:

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

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

    Ventana de terminal
    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.

    Ventana de terminal
    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.

    Ventana de terminal
    ghchronicle -config config.yaml

    Cada familia corre entonces con su propia cadencia: las ejecuciones de workflows cada quince minutos, el calendario de contribuciones cada doce horas.

Qué hace la primera pasada que las siguientes no hacen

Sección titulada «Qué hace la primera pasada que las siguientes no hacen»

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

  • Se recorre entera la lista de estrellas, página a página, para que cada estrella lleve la fecha en que se dio. Después, las cien más nuevas de cada repositorio viajan en una consulta GraphQL por cada diez.
  • 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.
  • El calendario de contribuciones de cada año, si every.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.

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.

Por dónde seguir

Sección titulada «Por dónde seguir»