GitHub App pour des commits et PR attribués à un bot

Par défaut, Takuto Core pousse les branches et ouvre les pull requests avec vos identifiants gh personnels (ou un token d’accès personnel restreint). Cela fonctionne, mais chaque commit et chaque PR vous sont attribués à vous.

Configurer une GitHub App permet plutôt à Takuto Core d’agir sous une identité de bot dédiée : les commits et les pull requests sont attribués au compte de l’App, et l’authentification repose sur un token d’installation à durée de vie courte que Takuto Core génère et renouvelle automatiquement — au lieu d’un token personnel à longue durée de vie qui traîne dans votre environnement.

Attribution, pas signature cryptographique. Cela fait du compte bot de l’App l’auteur/committer du travail. Cela ne signe pas vos commits en GPG/SSH : ils n’afficheront donc pas le badge vert Verified de GitHub — cela nécessite la signature des commits, qui est un sujet distinct. Si vous avez besoin de commits Verified, configurez la signature séparément dans votre workflow.

Pourquoi utiliser une identité de bot ?

Au-delà d’une attribution plus propre, faire passer le travail de l’agent par un compte bot vous apporte deux choses qui comptent pour la sécurité :

• Traçabilité. Chaque branche, commit et PR produit par l’agent est clairement attribué au bot plutôt que mêlé à votre propre travail — le relevé de ce que l’agent a fait est donc sans ambiguïté.
• De vrais garde-fous de revue, même en solo. Comme l’auteur de la PR est le bot et non vous, vous pouvez activer une règle de branch protection qui exige au moins une revue approuvée tout en relisant et approuvant vous-même les PR de l’agent. GitHub vous empêche normalement d’approuver votre propre PR : sans un auteur bot, un développeur solo ne peut donc imposer aucun garde-fou de revue. Avec lui, chaque changement passe par un second regard obligatoire avant de pouvoir être mergé — un vrai gain de sécurité.

Protégez vos branches — toujours. Un agent autonome peut faire tout ce que son token permet : les protections propres à votre dépôt sont donc le vrai filet de sécurité. Sur main (et toute branche que l’agent cible), activez la branch protection : exigez une pull request avant tout merge, exigez des revues approuvées, et interdisez les pushes directs. Takuto Core ne pousse jamais que des branches de fonctionnalité et n’ouvre que des PR — il ne devrait jamais pouvoir committer directement sur une branche protégée. Ne comptez pas sur le bon comportement de l’agent ; comptez sur les règles de branche.

Comment ça marche

Lorsque les identifiants d’App [github] sont renseignés, Takuto Core :

1. Construit un JWT signé avec la clé privée de votre App.
2. L’échange contre un token d’accès d’installation via l’API GitHub.
3. Configure git et gh dans chaque worktree pour utiliser ce token pendant le run.

Le token est limité à l’installation de l’App et renouvelé en arrière-plan : aucun PAT personnel n’est donc nécessaire pour les pushes ou la création de PR.

1. Créer l’App

Allez dans GitHub → Settings → Developer settings → GitHub Apps → New GitHub App (sous les paramètres de votre organisation s’il s’agit d’un dépôt d’organisation). Renseignez un nom et une URL de page d’accueil ; vous pouvez laisser le webhook inactif (Takuto Core interroge l’API, il ne reçoit pas de webhooks). Créez-la, puis notez l’App ID affiché sur la page de l’App.

2. Accorder les permissions du dépôt

Sous Permissions → Repository permissions de l’App, définissez exactement ce dont un run a besoin — la même surface que le token restreint :

Limitez-la aux seuls dépôts que l’agent doit toucher — rien de plus.

3. Générer une clé privée

Sur la page de l’App, sous Private keys, cliquez sur Generate a private key. GitHub télécharge un fichier .pem. Traitez-le comme un identifiant : stockez-le quelque part de monté dans le container, ou collez-le dans takuto.env — ne le committez jamais dans votre dépôt.

4. Installer l’App

Cliquez sur Install App et installez-la sur le compte/l’organisation propriétaire de votre dépôt, en ne choisissant que les dépôts sur lesquels Takuto Core doit travailler. Après l’installation, ouvrez la page des paramètres de l’installation — l’URL se termine par /installations/<number>. Ce nombre est votre installation ID.

5. Configurer Takuto Core

Renseignez les trois éléments dans la section [github]. Les trois champs doivent être fournis ensemble, et les deux champs de clé privée sont mutuellement exclusifs — utilisez un chemin ou une clé inline :

[github]
app_id = 123456
app_installation_id = 7654321
# Either point at a mounted PEM file…
app_private_key_path = "/run/secrets/takuto-app.pem"
# …or keep the key inline (prefer takuto.env over config.toml for this):
# app_private_key = "-----BEGIN RSA PRIVATE KEY-----\n…\n-----END RSA PRIVATE KEY-----"

Préférez garder la clé hors de config.toml : placez app_private_key dans takuto.env, ou montez le .pem et utilisez app_private_key_path. Voir la référence de configuration [github] pour la sémantique exacte des champs.

6. Redémarrer et vérifier

Redémarrez Takuto Core (takuto restart, ou docker compose up pour le chemin moteur). Lancez un workflow qui ouvre une PR, et vérifiez que le commit et la PR sont attribués au compte bot de votre App plutôt qu’à votre utilisateur personnel. Si l’authentification échoue, Takuto Core consigne une erreur d’API GitHub exploitable (par exemple, une installation introuvable ou une incohérence de permissions) — revérifiez l’App ID, l’installation ID et les permissions accordées ci-dessus.