Skip to main content

Contexto​

Los workflows de GitHub Actions reciben por default un GITHUB_TOKEN con permisos limitados: solo opera sobre el repo donde corre, no puede crear PRs si la org tiene esa restricción activa, y —crítico— los eventos que dispara no ejecutan otros workflows (por diseño, para evitar loops infinitos). Esto rompe muchos patrones útiles: bots de release que deben disparar pipelines downstream, automation cross-repo, o algo tan simple como /adr en una Discussion abriendo un PR que un workflow de validación recoja.

La salida histórica ha sido un Personal Access Token (PAT) de algún humano con permisos amplios. Funciona, pero acopla la automation a esa persona, los tokens son long-lived, y los scopes son granulares solo a nivel de tipo de operación, no por repo. Antes de empezar a montar pipelines (release de paquetes, bootstrap de ADRs, sync entre repos), conviene fijar la política por default para que las decisiones puntuales no se contradigan.

Decisión​

Cuando un pipeline o automation necesite un token con permisos más allá de los del GITHUB_TOKEN por default (por ejemplo: crear PRs, disparar workflows downstream, escribir en otros repos de la org, gestionar Discussions), la opción por default es emitir el token desde una GitHub App instalada en la org eigenoid. Los Personal Access Tokens (PATs) quedan reservados para casos puntuales y temporales.

Consecuencias​

  • Permisos de grano fino: cada App declara explícitamente qué scopes necesita y sobre qué repos; principio de mínimo privilegio.
  • Tokens de corta vida: el token de instalación expira en una hora; reduce el impacto si una clave se filtra.
  • Identidad clara: las acciones aparecen firmadas como la App (eigenoid-bot[bot]), no como una persona. Mejor auditoría.
  • Sin acoplamiento a una persona: el token no muere si el dueño rota PAT, deja la org o le rotan credenciales.
  • PRs creados por la App SÍ disparan workflows downstream (a diferencia de los creados con GITHUB_TOKEN), eliminando un gotcha frecuente.
  • Costo inicial de setup: hay que crear la App, generar private key, instalarla en cada repo y configurar secrets APP_ID + PRIVATE_KEY en cada workflow.
  • Una capa más a mantener: rotación periódica de la private key, gestión de quién es dueño humano de la App, monitoreo de qué repos la usan.

Alternativas evaluadas​

  • PAT de un usuario humano: simple de configurar pero acopla automation a esa persona; si se va o le rotan permisos, todo el pipeline se rompe. Tokens long-lived por default.
  • PAT de una cuenta bot dedicada: mejora la propiedad, pero GitHub cobra por seat adicional, los PATs siguen siendo long-lived y los permisos siguen siendo coarse-grained (scopes amplios).
  • Usar siempre GITHUB_TOKEN: gratis y automático, pero permisos limitados al repo donde corre el workflow y, crítico, los eventos disparados por sus acciones no ejecutan otros workflows (rompe automatizaciones encadenadas).
  • Deploy keys o tokens efímeros via OIDC a otro proveedor: válido para integraciones específicas (ej. cloud providers), no como mecanismo general dentro de GitHub.

Referencias​