Objetivos

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

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.

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 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

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. 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.