Création d’une GitHub App

Le canal Git avec provider = "github" s’authentifie en tant que GitHub App, et non en tant qu’utilisateur. L’application a sa propre identité de bot (your-app[bot]), ses propres permissions, et fonctionne sur chaque dépôt sur lequel elle est installée. Cette page guide la création unique de l’application et mappe chaque valeur sur la configuration du canal.

Fonctionne à la fois pour un compte personnel et une organisation : la seule différence est l’endroit où l’application est détenue et qui peut l’installer.

Documentation officielle : Les documentations de GitHub Enregistrement d’une application GitHub et Gestion des clés privées pour les applications GitHub constituent la référence principale pour tout le contenu de cette page.

1. Créez l’application

GitHub → Paramètres → Paramètres de développement → Applications GitHub → Nouvelle application GitHub.`

• Application personnelle : créez-la dans vos paramètres du développeur.
• Application d’organisation : commencez par basculer vers l’organisation (Paramètres → Paramètres du développeur pour l’organisation), afin que l’organisation possède l’application et que ses administrateurs puissent la gérer.

Remplissez :

1. Nom et URL de la page d’accueil : n’importe quelle URL valide ; l’application ne diffuse jamais de trafic web.
2. Webhook → Activé : décochez-le. Le canal interroge l’API REST ; il ne reçoit aucun webhook et n’a besoin d’aucune URL publique.
3. Autorisations du dépôt : accorder exactement ce que le canal utilise et rien de plus :
   • Problèmes : Lecture et écriture
   • Pull requests: Lecture et écriture
   • Contenu : Lecture seule (nécessaire pour les listes de fichiers des PR et les publications)
   • Métadonnées : Lecture seule (obligatoire ; sélectionné automatiquement)
   • Actions : Lecture seule, uniquement si vous acheminez des événements workflow_run.*
   • Conservez toutes les autres autorisations à Aucun accès.
4. Où cette application peut-elle être installée ? : “Uniquement sur ce compte” convient pour une configuration personnelle ou pour une seule organisation.

Cliquez sur Créer l’application GitHub.

2. Collecter les deux identifiants

Sur la page des paramètres de l’application après la création :

• ID d’application: affiché en haut. Il s’agit de app_id.
• Clés privées → Générer une clé privée. GitHub télécharge un seul .pem (RS256). Il s’agit de votre clé de signature ; GitHub ne conserve que la partie publique. Collez son contenu dans private_key ; le fichier .pem lui-même n’est pas référencé à l’exécution, vous pouvez donc supprimer le téléchargement une fois la clé enregistrée.

3. Installer l’application

Paramètres de l’application → Installer l’application → sélectionnez votre compte ou organisation → choisissez Tous les dépôts ou une sélection spécifique. L’installation est ce qui permet à l’application d’accéder aux dépôts ; sans elle, l’application peut s’authentifier mais ne voit rien.

Si l’application est installée sur un seul compte, vous pouvez laisser installation_id non défini : le canal liste les installations à la première utilisation et sélectionne automatiquement celle-ci, en échouant rapidement s’il en trouve zéro ou plusieurs. Définissez installation_id explicitement uniquement lorsque l’application dispose de plusieurs installations (un alias de canal sert une installation).

4. Associer à la configuration

Définissez chaque champ ci-dessous sur la surface de votre choix. La clé privée est un secret chiffré et dispose de son propre widget masqué ; les autres sont des champs simples.

**provider** : défini sur github.

zeroclaw config set channels.git.<alias>.provider <value>

app_id: l’App ID de l’étape 2.

zeroclaw config set channels.git.<alias>.app_id <value>

private_key: le PEM de l’étape 2. Il est intégré directement dans le seul magasin de configuration chiffré ; il n’existe aucun fichier de clé séparé sur le disque à protéger. Collez le PEM complet, y compris les lignes BEGIN/END ; le tableau de bord l’affiche sous forme de champ multi-lignes masqué.

channels.git.<alias>.private_key est une valeur secrète. Stocké sous forme chiffrée, jamais en texte brut dans config.toml. Définissez-le via l’une des méthodes suivantes, qui le chiffrent à l’écriture :

zeroclaw config set channels.git.<alias>.private_key    # demande une saisie masquée, stocke de manière chiffrée

repos: la liste owner/repo à surveiller. Laissez vide pour interroger tous les dépôts visibles par l’installation.

zeroclaw config set channels.git.<alias>.repos <value>

**installation_id`: optionnel, uniquement lorsque l’application possède plusieurs installations (étape 3). En cas d’unique installation, laissez-le non défini et le canal sera sélectionné automatiquement.

zeroclaw config set channels.git.<alias>.installation_id <value>

Pour la référence complète des champs, consultez la page Canal Git.

5. Vérifier

Le canal Git est inclus dans les artefacts de distribution standard, mais pas dans la configuration Cargo minimale par défaut. Pour une compilation personnalisée à partir des sources, incluez channel-git (ainsi que agent-runtime lors de la désactivation des fonctionnalités par défaut) :

cargo build --features channel-git

channel-git intègre tous les fournisseurs forge câblés en une seule compilation ; il n’existe pas de sous-ensemble plus petit par fournisseur, et compiler une fonctionnalité provider-* nue sans channel-git n’enregistre pas le canal.

Au démarrage, le canal génère un JWT d’application, l’échange contre un jeton d’installation et résout son propre login de bot. Un pull_request.opened ou une @-mention de l’application sur une issue devrait désormais atteindre l’agent. Si le démarrage échoue avec une erreur de clé privée manquante, private_key n’est pas défini ou est vide ; s’il échoue avec une erreur d’installation, l’application a zéro ou plusieurs installations, définissez donc installation_id. Consultez la page canal Git pour le routage des événements, la liaison peer-group et les notes d’exploitation.

Étapes suivantes

• Retour au canal : canal Git pour le routage des événements, le streaming, le budget de débit et la sécurité.
• Restreindre qui peut joindre l’agent : Peer Groups.
• Piloter l’automatisation à partir des événements forge : Procédures Opérationnelles Standard et le fan-in Git des SOP.
• Vous découvrez ZeroClaw ? Quickstart et Concepts.