Credenciales efímeras para agentes: qué cambia con GitHub Apps

Un agente de código necesita leer archivos, abrir ramas, comentar pull requests o actualizar checks. La tentación es entregarle una credencial amplia al iniciar el worker y recuperarla cuando termina. Ese diseño funciona mientras el token cabe en cada columna, atraviesa cada proxy, queda oculto en cada log y nunca sobrevive más que la tarea. Basta que una de esas suposiciones sea falsa para convertir una automatización útil en una ruta lateral hacia repositorios que el trabajo no necesitaba tocar.

El 2 de octubre de 2026, tres días calendario antes de este artículo en Lima, GitHub anunció que terminó el rollout iniciado el 27 de abril: los nuevos tokens de instalación de GitHub Apps se emiten por defecto en formato stateless ghs_APPID_JWT. Según el anuncio, ahora miden aproximadamente 520 caracteres en lugar de 40 y buscan acelerar emisión y validación y mejorar la fiabilidad de la API. Alcance por repositorio, permisos, endpoint y expiración de una hora no cambiaron. La noticia central es la finalización del rollout, no el inicio de una capacidad nueva de mínimo privilegio.

Una GitHub App representa una identidad de aplicación instalada por una organización o cuenta. El servicio firma un JWT como la app, identifica la instalación y solicita un access token. En esa solicitud puede reducir el conjunto de repositorios y permisos sin superar lo concedido a la instalación. La respuesta incluye el token, su expiración y el alcance efectivo; el token vence una hora después de crearse. Un SDK como Octokit puede encargarse de emitirlo de nuevo al expirar.

Stateless describe cómo GitHub emite y valida la credencial; no autoriza a decodificarla para tomar decisiones locales. La recomendación explícita es tratarla como una cadena opaca. Tampoco convierte por sí sola un agente en seguro: una credencial de una hora con escritura sobre cien repositorios sigue siendo demasiado poderosa para una tarea de lectura en uno. La arquitectura correcta separa identidad de instalación, intención del trabajo y capacidad temporal. El agente recibe solo la tercera y nunca la llave privada con la que podrían acuñarse capacidades nuevas.

Coloca la llave privada de la GitHub App en un broker de credenciales, no en la imagen del agente, su prompt, el runner compartido ni una variable disponible para todas las herramientas. El broker autentica la solicitud interna, resuelve tenant, instalación y trabajo, y decide si puede emitir. Después entrega un token de instalación ya acotado. Si el agente es comprometido mediante instrucciones maliciosas dentro de un issue, solo encuentra la capacidad del trabajo actual; no obtiene el material para fabricar otra con más alcance.

El contrato del broker debe aceptar una identidad de workload verificable y una intención estructurada, por ejemplo repositorio, pull request, operación y duración esperada. No acepte un campo libre como necesito acceso completo. Vincula cada emisión con job_id, instalación, repositorios, permisos, actor que aprobó y hash de política. Esa traza no guarda el token: guarda por qué existió. Si una plataforma ejecuta agentes de varios clientes, esta separación también evita que la caché o el proceso de un tenant reutilice la instalación de otro.

La instalación define un techo; cada tarea debe pedir menos. Un agente que resume un pull request necesita metadata y contenido de un repositorio, probablemente en lectura. Uno que publica un check puede requerir escritura de checks, pero no administración, secretos ni acceso a todos los repositorios de la organización. GitHub permite indicar repository_ids y permissions al crear el token. Si esos campos se omiten, la credencial hereda todo lo concedido a la instalación, que puede ser mucho más amplio que la intención del job.

Convierte cada herramienta en una operación declarada y mapea esa operación a permisos, no a roles vagos como agente-editor. Rechaza planes cuya secuencia requiere una capacidad no aprobada y solicita elevación explícita solo en el paso que la necesita. La respuesta 403 es una señal de política o de alcance, no una razón automática para reemitir con permisos totales. Mide además qué permisos emitidos se utilizaron realmente: la brecha entre concedido y usado señala dónde estrechar la siguiente política.

El salto de aproximadamente 40 a 520 caracteres es una prueba gratuita de supuestos ocultos. Recorre broker, cola, serializador, base de datos, secret store, sidecar, proxy, gateway y cliente HTTP. Elimina validaciones de longitud exacta y parsers que infieren privilegios desde puntos, prefijos o segmentos. Aumentar una columna no basta si un encabezado Authorization se trunca en middleware o si un validador de esquema rechaza el valor antes de llegar a GitHub.

GitHub retirará el 30 de noviembre de 2026 el header temporal X-GitHub-Stateless-S2S-Token que permitía forzar formatos durante la transición. Antes de quitarlo, ejecuta una matriz con ambos formatos sobre emisión, consumo, error 401, renovación y redacción. Después elimínalo del código de producción: dejar una bandera de migración como dependencia permanente crea una ruta que el proveedor ya anunció que dejará de respetar.

Una credencial efímera sigue siendo un secreto mientras vive. Entrégala al proceso exacto que realiza la llamada y, cuando sea viable, mantén el modelo separado del ejecutor que construye Authorization. No la incluyas en mensajes de herramientas, eventos, spans, dumps de error, argumentos de línea de comandos ni artefactos de evaluación. Si el agente necesita varias APIs, usa credenciales independientes por proveedor; una cadena de entorno común convierte el compromiso de una herramienta en exposición de todas.

Actualiza la redacción para valores largos y variantes futuras sin depender únicamente de la regex histórica de 40 caracteres. La defensa principal es no registrar headers sensibles; la detección por patrón es una segunda barrera. Prueba logs de aplicación, proxy y observabilidad con valores sintéticos que tengan puntos, guiones y guiones bajos, y verifica que no aparezca ni el token completo ni fragmentos útiles. Conserva identificadores de emisión no secretos para correlacionar incidentes sin copiar credenciales.

Una hora es un límite superior, no la duración prometida del job. El token puede expirar durante una ejecución larga, ser revocado o quedar inválido por un cambio de instalación. Modela credencial válida, próxima a vencer, vencida y revocada. Renueva mediante el broker con la misma política y vuelve a validar la intención actual: un job que cambió de repositorio o pasó de lectura a escritura no debe reciclar automáticamente su aprobación inicial.

Ante un 401, evita una tormenta donde cada herramienta acuña su propio token y repite una mutación. Centraliza renovación, usa exclusión por job y vuelve a intentar solo operaciones idempotentes o protegidas por una clave de idempotencia. Para detener un incidente, revoca el token y suspende nuevas emisiones para instalación, tenant o política; luego invalida workers pendientes. La recuperación se considera completa cuando no hay emisiones nuevas, las capacidades activas vencieron o fueron revocadas y la auditoría explica qué operaciones alcanzaron GitHub.

Ejemplo hipotético: un agente recibe un issue para actualizar una dependencia en repo-pagos. El orquestador construye un plan con lectura de contenido, creación de branch, escritura de contenido y apertura de pull request. El broker verifica que el issue pertenece al tenant, emite un token limitado a repo-pagos con los permisos correspondientes y registra la decisión. Una instrucción incrustada intenta leer repo-nómina: la herramienta la bloquea porque ese repositorio no está en el alcance, sin pedir una elevación automática. Al terminar el pull request, el token se descarta y el job conserva solo la evidencia no secreta.

Evalúa cinco suites: alcance, transporte, secreto, ciclo de vida y recuperación. Inyecta repositorios no autorizados y permisos ausentes; envía tokens sintéticos largos por toda la ruta; provoca logs y errores; adelanta el reloj y simula revocación; corta la red después de una mutación. El criterio no es solo que el happy path publique un pull request. Debe probar que una acción fuera del contrato no llega a GitHub, que ningún log revela la credencial, que una renovación conserva o reduce alcance y que un retry no duplica efectos.

Los tokens stateless no eliminan la necesidad de almacenamiento seguro, no reducen permisos automáticamente y no protegen contra una herramienta que usa correctamente una credencial demasiado amplia. Tampoco sustituyen revisión humana en cambios de alto impacto ni controles sobre comandos, red y artefactos. Su valor editorial está en hacer visible una deuda que ya existía: si 480 caracteres adicionales rompen la integración, probablemente el sistema también tenía supuestos frágiles sobre quién puede acuñar, transportar y observar el secreto.

Aprueba la integración cuando los cinco gates dejan evidencia: emisor aislado, alcance derivado del plan, transporte opaco, distribución mínima y recuperación ensayada. La unidad de autorización no debe ser el agente genérico, sino un trabajo identificado con un propósito y un límite. Si necesitas convertir esta frontera en un piloto de agentes con herramientas, permisos, trazas y evaluaciones, el servicio de agentes a medida de Wasyra puede ayudar a diseñarla. Es un servicio de implementación separado del producto disponible en agents.wasyra.com.