# El token

Qué familias compra cada permiso, y por qué el GITHUB_TOKEN automático no basta.

Source: https://jmrplens.github.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, 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 | El tráfico es un 403. GitHub solo muestra visitas y clones a quien podría hacer push                   |
| `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. No es un permiso de lectura en absoluto:
GitHub decide quién puede ver visitas y clones preguntando si quien llama
podría hacer push, así que un token de solo lectura recibe un 403 en cada
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.

- **Está limitado a un repositorio.** El tráfico necesita acceso de escritura a
  _cada_ repositorio que se recoja. El token automático lo tiene para el
  repositorio en el que corre el workflow, y para ninguno más.
- **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](/ghchronicle/es/install/actions/).

## Funcionar sin token

Es posible, y conviene ser honesto sobre lo que cuesta. Una tarjeta de números
públicos se puede dibujar con llamadas sin autenticar, pero los paneles de
tráfico y de alertas quedarán vacíos y el log dirá `not available (403)` en
cada uno. Eso es el colector informando de un permiso, no de un fallo.