# El token

Qué familias de ghchronicle compra cada permiso del token de GitHub, y por qué el GITHUB_TOKEN automático de un workflow no basta.

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

Todo aquí es acceso de lectura. El colector nunca escribe en GitHub. Lo que
varía es cuánto de la cuenta se le permite ver a un token dado, y hay unos
cuantos permisos que conviene entender en vez de limitarse a concederlos.

## Cómo crearlo

1. Ve a `https://github.com/settings/tokens`.

2. Elige el tipo de token y dale los permisos de abajo.

    - **Clásico**

      `repo`, `read:packages`, `read:user`, `read:org`, `security_events`,
      `read:public_key` y `read:gpg_key` cubre todo lo que esto recoge.

    - **Fine-grained**

      Acceso de lectura a los repositorios, incluido el permiso de
      repositorio Administration, que es el que pide el tráfico, más los
      permisos de cuenta para seguidores, gists, paquetes, plan, claves SSH de
      Git y claves GPG.

3. Ponlo donde el proceso pueda leerlo, y en ningún otro sitio.

    ```sh
    export GITHUB_TOKEN=github_pat_...
    ```

    El fichero de configuración lo referencia como `${GITHUB_TOKEN}`, que se
    expande desde el entorno al arrancar. Eso es lo que permite versionar el
    fichero dejando el token fuera.

## Qué compra cada permiso

| Permiso                            | Sin él                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Acceso de escritura al repositorio, y Administration (lectura) en un token fine-grained | El tráfico es un 403. GitHub solo muestra visitas y clones a quien puede hacer push al repositorio |
| `security_events`                  | Las alertas de Dependabot y de code scanning parecen exactamente un repositorio con la función apagada |
| `read:packages`                    | El registro de contenedores es invisible. Las versiones de paquete cuestan una llamada por paquete     |
| `read:user`                        | Faltan seguidores, contribuciones, gists y cuentas sociales                                            |
| `read:org`                         | Los repositorios de una organización no se descubren                                                   |
| `read:public_key`, `read:gpg_key`  | La familia `keys` no escribe nada, y no lo dice. Ningún otro permiso implica ninguno de los dos        |

El del tráfico es el que sorprende, porque poder leer un repositorio no basta.
GitHub solo muestra visitas y clones a quien puede hacer push al repositorio, y
un token fine-grained necesita además el
[permiso de repositorio Administration (lectura)](https://docs.github.com/es/rest/metrics/traffic#get-repository-clones--fine-grained-access-tokens);
un token al que le falte cualquiera de los dos recibe un 403 en ese
repositorio. El colector lo anota como "no disponible" y sigue, que es por lo
que el síntoma es un panel de tráfico vacío y no una pasada fallida.

> **No disponible no es un error**
>
> Todo lo que el token no puede ver se anota como no disponible y se salta. Un
> repositorio con una función apagada no debe detener la pasada de los otros
> cuarenta, así que el log dice `not available (403)` y la pasada continúa.

## Por qué el GITHUB_TOKEN automático no basta

Un workflow recibe un `GITHUB_TOKEN` gratis. No basta para esto, y la razón
merece decirse con precisión en vez de dejar que alguien la descubra como un
dashboard vacío.

- **No puede leer el tráfico, ni siquiera el suyo.** El tráfico necesita acceso
  de escritura a _cada_ repositorio que se recoja, y el token automático solo
  lo tiene para el repositorio en el que corre el workflow. Incluso ahí recibe
  un 403: GitHub pide además el permiso de repositorio Administration, que un
  workflow no puede conceder a su token automático.
- **No tiene `security_events`.** Las alertas de Dependabot y de code scanning
  le son invisibles.
- **No tiene `read:packages`.** El registro de contenedores le es invisible.
- **No es un usuario.** Todo lo que es de cuenta (seguidores, el calendario de
  contribuciones, la facturación, las notificaciones, las estrellas que diste)
  va sobre la persona, no sobre un repositorio, y el token automático es una
  instalación, no una persona.

Así que un workflow necesita un token personal guardado como secreto del
repositorio y pasado por la entrada `token`. Ver
[GitHub Actions](https://docs.jmrp.io/ghchronicle/es/install/actions/).

## Funcionar sin token

Solo para las tres órdenes que no preguntan nada a GitHub: `-backfill-status`,
`-publish-dashboard` y `-uninstall`. Todo lo que recoge, una tarjeta de números
públicos incluida, necesita uno, y sin él se para al arrancar con
`github.token is empty and GITHUB_TOKEN is unset`. Lo que cuesta un token al
que le falta un permiso es la tabla de arriba: la parte que no puede ver queda
vacía, y el log dice `not available (403)` para cada una, que es el colector
informando de un permiso, no de un fallo.