# Objetivos

Qué repositorios toca una pasada, y por qué los forks y los archivados quedan fuera por omisión.

Source: https://docs.jmrp.io/ghchronicle/es/configuration/targets/

El bloque `targets` decide qué repositorios de GitHub recoge una pasada: los de una cuenta, los de sus organizaciones y los que se nombren.

```yaml
targets:
  user: your-github-login
  orgs: []
  repos: []
  exclude: []
  include_forks: false
  include_archived: false
  include_private: true
```

## Las claves

| Clave              | Por omisión | Qué hace                                                   |
| ------------------ | ----------- | ---------------------------------------------------------- |
| `user`             | ninguno     | La cuenta que recoger. Sus repositorios se descubren solos |
| `orgs`             | `[]`        | Organizaciones que incluir además                          |
| `repos`            | `[]`        | Repositorios que recoger digan lo que digan los filtros    |
| `exclude`          | `[]`        | Globs de shell, comparados contra `owner/name`             |
| `include_forks`    | `false`     | Si se recogen los forks                                    |
| `include_archived` | `false`     | Si se recogen los repositorios archivados                  |
| `include_private`  | `true`      | Si se recogen los repositorios privados                    |

Hay que poner al menos uno de `user`, `orgs` o `repos`, o el arranque falla con
`targets: set at least one of user, orgs or repos`.

`user` es además lo que hace posibles las familias de cuenta. Una configuración
que solo nombra repositorios no tiene login que darle a GraphQL, así que el
calendario de contribuciones, el feed de eventos, las notificaciones, la
facturación, los paquetes y las familias salientes se saltan todas.

## Nombrar un repositorio anula toda exclusión

`repos` no es otro filtro. Es una declaración de intenciones, y gana: nombrar
`someone/thing` lo recoge aunque sea un fork, aunque esté archivado y aunque un
glob de `exclude` lo hubiera capturado.

```yaml
targets:
  user: acme
  repos:
    - someone-else/a-fork-i-actually-maintain
  exclude:
    - "acme/experiment-*"
```

`exclude` acepta globs de shell, así que `someone/experiment-*` descarta un
prefijo entero en una línea.

Nombrar uno de los repositorios de la propia cuenta, un fork tuyo por ejemplo,
no cuesta ninguna petición para descubrirlo: el listado ya lo devolvió, con las
cuatro cosas que el descubrimiento quiere saber de él. Solo un nombre que ningún
listado devuelve, el repositorio de otra persona o uno de una organización que
no está en `orgs`, se lee aparte cada vez que se reconstruye la lista.

## Por qué forks y archivados están apagados por omisión

Ambos valores por defecto existen por la misma razón, que es el límite de
peticiones.

- **El tráfico de un fork es casi siempre cero.** GitHub informa de visitas y
  clones por repositorio, y para un fork que nadie visita eso son catorce días
  de ceros por pasada. Cuesta cuatro llamadas por repositorio para no aprender
  nada.
- **Un repositorio archivado ya no da trabajo.** Sus estrellas, sus forks y
  sus watchers todavía pueden moverse, y esos se leen de todos modos, como se
  explica abajo. Nada más puede, y recogerlo gasta el presupuesto en filas que
  ya no se mueven.

Actívalos cuando la suposición no valga en tu caso. Un fork en el que de verdad
desarrollas es un repositorio real con tráfico real, y `repos` es la forma de
nombrarlo sin recoger también los cuarenta marcadores.

Apagado no es invisible, por dos vías. Un repositorio archivado sigue teniendo
dos filas en cada pasada de `totals`: `gh_repo_archived`, fechada en el
instante en que se archivó, y `gh_repo_total`, sus contadores de toda la vida
tal como están, estrellas y forks incluidos, sellada en la pasada. El listado
que una pasada ya paga dice qué repositorios están archivados, y la familia
`totals` pregunta por todos en una consulta por cada veinticinco a su propia
cadencia, así que la tabla _Repositories archived_ existe desde la primera
pasada, los totales de estrellas y forks de la cuenta los cuentan, y el coste
es un punto por cada veinticinco repositorios archivados en cada pasada de
`totals`. Y un
[relleno histórico](https://docs.jmrp.io/ghchronicle/es/how/backfill/) recoge los repositorios
archivados enteros diga lo que diga esta clave, porque su historia es la
historia de la cuenta y basta con recorrerla una vez. Los forks quedan como
estén configurados en ambos casos: un fork archivado con `include_forks: false`
no tiene fila.

> **Comprueba el conjunto antes de gastar cuota en él**
>
> ```sh
> ghchronicle -config config.yaml -list
> ```
>
> Eso imprime los repositorios en alcance y no escribe nada. Si falta algo que
> esperabas, esta es la orden que te lo dice antes de que una pasada gaste cuota
> en el conjunto equivocado.

## Repositorios privados

`include_private` vale `true` por omisión, porque un token que puede verlos se
concedió a propósito y el objetivo de la herramienta es guardar la historia de
la cuenta, no de su mitad pública.

Lo que se guarda son las mismas medidas que para un repositorio público:
recuentos, duraciones y nombres. Conviene saber dos cosas sobre lo que eso
implica:

- Los nombres de repositorio y de rama aparecen como valores de etiqueta, así
  que serán visibles para cualquiera que pueda leer el dashboard.
- Solo se guarda el _host_ de una URL de webhook, nunca la ruta, porque la ruta
  suele llevar un secreto.

Ponlo a `false` para recoger solo repositorios públicos.

## La cadencia del descubrimiento

La lista de repositorios se rehace una vez por hora: en la primera pasada una
hora después del último listado, con medio tic de margen, el mismo que recibe
[la cadencia de una
familia](https://docs.jmrp.io/ghchronicle/es/configuration/cadences/#heartbeat-el-tic-del-bucle-que-no-es-una-cadencia).
Los repositorios se crean pocas veces y listarlos cuesta una página por cada
cien, así que un repositorio nuevo puede tardar hasta una hora en entrar en la
pasada. Antes de la 2.6.1 la lista no tenía margen y podía sobrevivir por unos
milisegundos a la pasada de una hora después, así que con el tic de cuarto de
hora un repositorio nuevo esperaba hasta una hora y cuarto la mitad de las
veces. Nombrarlo en `repos` no cambia eso; reiniciar el proceso sí, y también
cada `-once`, que los lista de nuevo.