# Inicio rápido

Instalar ghchronicle, apuntarlo a una base de datos y lanzar la primera pasada sobre una cuenta de GitHub, y qué hace esa primera pasada que las siguientes no hacen.

Source: https://docs.jmrp.io/ghchronicle/es/start/quickstart/

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:

```sh
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**

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

      En Windows, desde PowerShell:

      ```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](https://github.com/jmrplens/ghchronicle/releases) y pon
      `ghchronicle` en el `PATH`.

    - **Contenedor**

      ```sh
      docker pull ghcr.io/jmrplens/ghchronicle
      ```

    - **Go**

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

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

    ```sh
    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](https://docs.jmrp.io/ghchronicle/es/start/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:

    ```yaml
    # 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:

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

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

    ```sh
    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.**

    ```sh
    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.**

    ```sh
    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](https://docs.github.com/es/rest/activity/starring#new-access-restrictions)
  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](https://docs.jmrp.io/ghchronicle/es/configuration/#la-caché-que-hay-a-su-lado).

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](https://docs.jmrp.io/ghchronicle/es/how/backfill/) 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](https://docs.jmrp.io/ghchronicle/es/configuration/#state_file). 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](https://docs.jmrp.io/ghchronicle/es/install/) es lo que convierte la orden
  de arriba en algo que sigue corriendo: systemd, Docker o una Action
  programada.
- [La fecha del punto](https://docs.jmrp.io/ghchronicle/es/how/dating/) es la idea de diseño de la
  que se deriva todo lo demás.
- [Elegir almacén](https://docs.jmrp.io/ghchronicle/es/sinks/) decide qué preguntas podrás hacer
  después.
- [Coste de una pasada](https://docs.jmrp.io/ghchronicle/es/api/cost/) es el precio medido en
  llamadas a la API.