Git

Interagissez avec l’agent via les commentaires des issues et des pull requests d’une forge Git, et exposez les événements du dépôt, incluant le cycle de vie des PR, les commentaires de révision, les résultats CI et les releases, via une table de routage par événement. Le canal est structuré autour d’un seam de fournisseur : un champ provider permet de sélectionner la forge. GitHub, Gitea et Forgejo sont des fournisseurs intégrés ; d’autres forges s’ajoutent en tant que fournisseurs équivalents sans modifier le canal générique.

Nouveau sur ZeroClaw ? Commencez par le Quickstart pour faire fonctionner un agent, puis parcourez Concepts pour les termes (agent, groupe de pairs, autonomie, SOP) que cette page suppose.

Avec le fournisseur GitHub, ZeroClaw s’authentifie en tant que GitHub App et répond sous l’identité de bot propre à l’application (your-app[bot]), ce qui lui permet de fonctionner sur n’importe quel dépôt sur lequel l’application est installée. Il n’y a ni jeton d’accès personnel ni compte utilisateur partagé.

Avec le fournisseur Gitea/Forgejo, ZeroClaw s’authentifie avec un jeton d’accès personnel auprès de l’API compatible Gitea de l’instance et répond en tant que propriétaire du jeton.

Remarque de compilation : le canal Git est inclus dans les artefacts de distribution standard, mais pas dans la configuration par défaut allégée de Cargo. Les compilations personnalisées à partir des sources doivent ajouter channel-git ; les compilations qui désactivent les fonctionnalités par défaut doivent également ajouter agent-runtime. La fonctionnalité channel-git intègre tous les fournisseurs de forge pris en charge, de sorte qu’un seul binaire prend en charge toutes les forges compatibles ; il n’existe pas de sous-ensemble de compilation plus réduit, par fournisseur, à sélectionner.

Qui peut parler à l’agent

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour git définit channel sur git, liste les expéditeurs autorisés dans external_peers (pour git, le nom d’utilisateur (identifiant) de la forge de l’auteur du commentaire ; ["*"] accepte n’importe qui), nomme éventuellement les agents pairs pour le dispatch inter-agents, une liste noire ignore, et une output_modality (mirror, voice ou text). Voir Groupes de pairs pour la référence des champs.

Où définir ce paramètre :

Comment ça fonctionne

• Polling, pas de webhooks. Le canal interroge l’API REST de la forge pour les nouvelles issues, pull requests et commentaires à partir d’un curseur since. Le daemon n’a besoin d’aucune URL publique, tunnel ni accès entrant ; il fonctionne derrière un NAT.
• Conversations limitées à une issue. Tous les messages sur une même issue ou PR partagent un seul fil de conversation ; l’agent répond sous forme de commentaire sur cette issue.
• Réponses en continu. L’agent publie un commentaire brouillon et le modifie sur place à mesure que la réponse progresse (les modifications sont espacées de ≥ 2 s pour respecter les limites anti-abus du forge).
• Réactions. Les réactions de reconnaissance correspondent à l’ensemble des réactions de la forge (avec GitHub : 👀 → eyes, ✅ → +1, ⚠️ → confused, …) ; les emoji non mappables sont ignorés.
• Démarrage à froid. Les événements créés avant le démarrage du démon ne sont jamais traités, le redémarrage ne permet donc pas de rejouer l’historique. L’inconvénient : les commentaires publiés pendant l’arrêt du démon ne sont pas pris en compte, veuillez donc mentionner l’application à nouveau.
• Les modifications de commentaires sont ignorées. Seuls les commentaires nouvellement créés et les publications d’ouverture d’issue/PR déclenchent l’agent.

Identifiants

Chaque fournisseur s’authentifie différemment, et chacun dispose d’un guide étape par étape complet :

• GitHub s’authentifie en tant qu’application GitHub (App ID plus une clé privée générée). Voir Création d’une application GitHub.
• Gitea / Forgejo s’authentifie à l’aide d’un jeton d’accès personnel auprès de l’API compatible Gitea de l’instance. Voir Créer un jeton Gitea / Forgejo (Codeberg).

Configurer

Définissez les champs de canal sur la surface de votre choix :

La référence complète des champs, directement depuis le schéma :

zeroclaw config set channels.git.<alias>.access_token    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__git__<alias>__access_token=

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

export ZEROCLAW_channels__git__<alias>__api_base_url=

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

export ZEROCLAW_channels__git__<alias>__app_id=

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

export ZEROCLAW_channels__git__<alias>__events=

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

export ZEROCLAW_channels__git__<alias>__events_backbone=

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

export ZEROCLAW_channels__git__<alias>__excluded_tools=

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

export ZEROCLAW_channels__git__<alias>__installation_id=

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

export ZEROCLAW_channels__git__<alias>__listen_to_bots=

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

export ZEROCLAW_channels__git__<alias>__mention_only=

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

export ZEROCLAW_channels__git__<alias>__poll_interval_secs=

zeroclaw config set channels.git.<alias>.private_key    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__git__<alias>__private_key=

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

export ZEROCLAW_channels__git__<alias>__private_key_path=

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

export ZEROCLAW_channels__git__<alias>__provider=

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

export ZEROCLAW_channels__git__<alias>__proxy_url=

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

export ZEROCLAW_channels__git__<alias>__repos=

L’alias default est l’instance initiale courante. C’est également celui que les envois ponctuels utilisent : zeroclaw channel send --channel-id git recherche spécifiquement l’alias default. Nommez donc l’instance default, sauf si tous les envois proviennent d’un agent lié à un alias portant un autre nom. Laissez repos vide pour interroger tous les dépôts accessibles avec les identifiants, ou définissez une liste explicite de dépôts pour réduire l’utilisation du quota. Définissez listen_to_bots uniquement si les commentaires provenant d’autres comptes de bots doivent être traités. Une valeur provider inconnue provoque une erreur explicite au démarrage, plutôt qu’un repli silencieux.

La configuration des identifiants varie selon le fournisseur et chacun dispose de son propre secret chiffré ; les deux tutoriels le couvrent de bout en bout :

• GitHub : ID d’application et une clé privée. Voir Création d’une application GitHub.
• Gitea / Forgejo : un jeton d’accès et une URL de base de l’API. Voir Création d’un jeton Gitea / Forgejo (Codeberg).

Événements & routage

Au-delà de la conversation, le canal normalise l’activité du dépôt en événements typés et redirige chaque type d’événement en fonction de la configuration. Le routage d’un événement vers sop le dispatche vers une Procédure Opérationnelle Standard, une procédure déterministe et auditable avec correspondance des déclencheurs et portes d’approbation. La page Git SOP fan-in détaille précisément comment un événement de forge devient une exécution de SOP.

Types d’événements connus : issue_comment.created, issues.opened, pull_request.opened, pull_request.closed, pull_request.merged, pull_request_review_comment.created, workflow_run.completed, workflow_run.failed, release.published.

• Par défaut. En l’absence de tableau events, le canal se comporte de manière conversationnelle : issue_comment.created, issues.opened et pull_request.opened sont transmis en tant que messages (filtrés par mention comme décrit ci-dessus) ; tout le reste est ignoré. Les types d’événements absents d’un tableau non vide bénéficient des mêmes valeurs par défaut par type : lister workflow_run.failed ne désactive pas le mode conversationnel. Une entrée ne contenant ni message = true ni sop désactive explicitement ce type d’événement.
• Le routage d’un type d’événement correspond à son abonnement. Le canal déduit les endpoints API à interroger à partir du tableau : les commentaires de revue, les publications et les exécutions d’Actions ne sont récupérés que lorsque leurs types d’événements sont routés, ainsi un canal non configuré coûte exactement ce qu’il coûtait auparavant. GitHub prend en charge tous les types d’événements répertoriés ; le fournisseur Gitea/Forgejo prend en charge les commentaires d’issue, les ouvertures d’issue/PR, les transitions de clôture/fusion de PR, les publications, les réponses, les modifications, les suppressions et les réactions.
• Routage de sop. Une route sop émet un événement SOP provenant d’un canal, avec pour topic git.<alias>:<event_type> et une charge utile JSON structurée. L’événement routé est consommé par l’ingress SOP plutôt que transmis comme un message de chat. Faites-le correspondre dans SOP.toml à l’aide d’un déclencheur channel qui nomme le canal et l’instance (channel = "git", alias = "main"); la chaîne git.<alias>:<event_type> est le topic d’événement généré par le canal, et non un champ du déclencheur. Utilisez une condition facultative pour affiner davantage, par ex. $.event_type == "pull_request.opened" ou $.repo == "octo/repo".
• Filtrage des mentions par route. Le filtre mention_only s’applique aux événements conversationnels sur le chemin de messagerie. Les événements sop-routés l’ignorent : un PR acheminé vers pr-triage est capté que l’auteur ait mentionné l’application ou non. Les événements Lifecycle/CI/release n’ont pas de surface de mention et ne sont jamais filtrés. L’activité de l’application elle-même est systématiquement ignorée ; l’activité des autres bots suit listen_to_bots ; chaque événement passe la liste d’autorisation du groupe pair en fonction de l’identifiant de l’auteur.
• Surfaces de réponse. Les événements de commentaire, d’issue et de PR répondent dans le fil de discussion correspondant à l’issue/PR. Les événements de workflow-run répondent à la PR associée à l’exécution lorsque la forge en indique une ; sinon, ainsi que pour les releases, la cible est le dépôt nu et l’agent ne peut pas répondre sur la plateforme (redirigez-les vers une SOP ou traitez-les via d’autres outils).
• Backbone de l’API Events (optionnel, GitHub). events_backbone = true interroge également /repos/{owner}/{repo}/events à l’aide de requêtes conditionnelles ETag (une requête par dépôt par cycle ; un dépôt inactif renvoie un 304 et ne coûte presque rien). Limitations : le flux peut présenter un retard d’environ ~5 minutes maximum, les payloads sont tronqués, et les événements Actions n’y apparaissent jamais : les exécutions de workflow utilisent toujours leur point de terminaison dédié. Tout élément renvoyé à la fois par le flux et un point de terminaison ciblé est dédupliqué, il est donc possible de les combiner en toute sécurité. Gitea/Forgejo ignorent cette option actuellement.

Notes de fonctionnement

• Budget de taux : sur GitHub, chaque installation obtient 5 000 requêtes/heure ; la valeur par défaut conversationnelle consomme 2 requêtes par dépôt par tick de poll (5 dépôts à un intervalle de 30 s ≈ 1 200/h). Chaque famille d’endpoints supplémentaire acheminée (review comments, releases, Actions runs) ajoute 1 requête par dépôt et par tick, et le backbone de l’API Events ajoute 1 requête conditionnelle (les 304 pour les dépôts inactifs sont pratiquement gratuits). Les limites de taux Gitea/Forgejo dépendent de l’instance. En cas de réponse de dépassement de limite, le canal applique un backoff jusqu’à la réinitialisation de la fenêtre de limite.
• De nombreux dépôts : lorsque repos est vide et que l’identifiant peut voir plus de 100 dépôts, seule la première page est récupérée (un avertissement est enregistré pour GitHub). Listez explicitement repos dans ce cas.

Sécurité

Les commentaires sur les issues et les PR des dépôts publics constituent des entrées hostiles. Maintenez mention_only = true, contrôlez l’accès des expédieurs via un groupe de pairs (un ensemble de pairs vide refuse à tous, ["*"] accepte tout le monde), et maintenez l’autonomie à Supervised ou un niveau inférieur pour les dépôts publics. Il s’agit des mêmes recommandations que pour les canaux sociaux.

Docs associés

• Configurer les identifiants : Créer une application GitHub · Créer un jeton Gitea / Forgejo (Codeberg)
• Qui peut accéder à l’agent : Groupes de pairs
• Ce que l’agent peut faire : Sécurité et autonomie · Niveaux d’autonomie
• Automatisation événementielle : Procédures opérationnelles standard · Git SOP fan-in
• Vue d’ensemble : Agents · Aperçu des canaux