GitHub App para commits y PRs atribuidos a un bot

Por defecto, Takuto Core sube ramas y abre pull requests usando tus credenciales personales de gh (o un token de acceso personal acotado). Eso funciona, pero cada commit y cada PR se atribuyen a ti.

Configurar en su lugar una GitHub App permite que Takuto Core actúe como una identidad de bot dedicada: los commits y los pull requests se atribuyen a la cuenta de la App, y la autenticación usa un token de instalación de corta duración que Takuto Core genera y rota automáticamente — en lugar de un token personal de larga duración presente en tu entorno.

Atribución, no firma criptográfica. Esto convierte a la cuenta de bot de la App en el autor/committer del trabajo. No firma tus commits con GPG/SSH, así que no mostrarán la insignia verde Verified de GitHub — eso requiere firma de commits, que es un asunto aparte. Si necesitas commits Verified, configura la firma en tu workflow por separado.

¿Por qué usar una identidad de bot?

Más allá de una atribución más limpia, encauzar el trabajo del agente a través de una cuenta de bot te aporta dos cosas que importan para la seguridad:

• Trazabilidad. Cada rama, commit y PR que produce el agente queda claramente atribuido al bot en lugar de mezclarse con tu propio trabajo — así el registro de lo que hizo el agente es inequívoco.
• Verdaderas barreras de revisión, incluso trabajando en solitario. Como el autor del PR es el bot y no tú, puedes habilitar una regla de branch protection que exija al menos una revisión aprobatoria y aun así revisar y aprobar tú mismo los PRs del agente. GitHub normalmente te impide aprobar tu propio PR, así que sin un autor bot un desarrollador en solitario no puede imponer ninguna barrera de revisión. Con él, cada cambio recibe un segundo par de ojos obligatorio antes de poder mergearse — una gran ganancia de seguridad.

Protege tus ramas — siempre. Un agente autónomo puede hacer cualquier cosa que su token le permita, así que las propias protecciones de tu repositorio son la verdadera red de seguridad. En main (y en cualquier rama a la que apunte el agente), activa la branch protection: exige un pull request antes de mergear, exige revisiones aprobatorias y prohíbe los pushes directos. Takuto Core solo sube ramas de feature y abre PRs — nunca debería poder hacer commit directamente a una rama protegida. No confíes en que el agente se comporte; confía en las reglas de las ramas.

Cómo funciona

Cuando se establecen las credenciales de App en [github], Takuto Core:

1. Construye un JWT firmado con la clave privada de tu App.
2. Lo intercambia por un token de acceso de instalación mediante la API de GitHub.
3. Configura git y gh dentro de cada worktree para que usen ese token durante la ejecución.

El token está acotado a la instalación de la App y se refresca en segundo plano, así que no hace falta ningún PAT personal para los pushes o la creación de PRs.

1. Crea la App

Ve a GitHub → Settings → Developer settings → GitHub Apps → New GitHub App (bajo la configuración de tu organización si es un repo de organización). Rellena un nombre y una URL de homepage; puedes dejar el webhook inactivo (Takuto Core hace polling, no recibe webhooks). Créala y anota el App ID que se muestra en la página de la App.

2. Concede permisos sobre el repositorio

En Permissions → Repository permissions de la App, establece exactamente lo que necesita una ejecución — la misma superficie que el token acotado:

Mantenlo acotado a los repositorios concretos que el agente deba tocar — nada más.

3. Genera una clave privada

En la página de la App, bajo Private keys, haz clic en Generate a private key. GitHub descarga un archivo .pem. Trátalo como una credencial: guárdalo en algún lugar montado dentro del container, o pégalo en takuto.env — nunca lo subas a tu repositorio.

4. Instala la App

Haz clic en Install App e instálala en la cuenta/organización propietaria de tu repositorio, eligiendo solo los repositorios en los que Takuto Core deba trabajar. Tras instalarla, abre la página de configuración de la instalación — la URL termina en /installations/<number>. Ese número es tu installation ID.

5. Configura Takuto Core

Establece las tres piezas en la sección [github]. Los tres campos deben proporcionarse juntos, y los dos campos de clave privada son mutuamente excluyentes — usa una ruta o una clave en línea:

[github]
app_id = 123456
app_installation_id = 7654321
# O bien apunta a un archivo PEM montado…
app_private_key_path = "/run/secrets/takuto-app.pem"
# …o bien mantén la clave en línea (mejor takuto.env que config.toml para esto):
# app_private_key = "-----BEGIN RSA PRIVATE KEY-----\n…\n-----END RSA PRIVATE KEY-----"

Prefiere mantener la clave fuera de config.toml: pon app_private_key en takuto.env, o monta el .pem y usa app_private_key_path. Consulta la referencia de configuración de [github] para la semántica exacta de cada campo.

6. Reinicia y verifica

Reinicia Takuto Core (takuto restart, o docker compose up para la vía del motor). Ejecuta un workflow que abra un PR y confirma que el commit y el PR se atribuyen a la cuenta de bot de tu App en lugar de a tu usuario personal. Si la autenticación falla, Takuto Core registra un error accionable de la API de GitHub (por ejemplo, una instalación no encontrada o un desajuste de permisos) — vuelve a comprobar el App ID, el installation ID y los permisos concedidos arriba.