Git

Conversa con el agente a través de los comentarios de un issue y una pull request de un forge git, y expone eventos del repositorio, incluidos el ciclo de vida de la PR, los comentarios de revisión, los resultados de CI y los lanzamientos, mediante una tabla de enrutamiento por evento. El canal se construye en torno a una costura del proveedor: un campo provider selecciona el forge. GitHub, Gitea y Forgejo son proveedores integrados; forges adicionales se incorporan como proveedores hermanos sin cambiar el canal genérico.

¿Nuevo en ZeroClaw? Empieza con la Guía de inicio rápido para poner en marcha un agente, y luego revisa Conceptos para los términos (agente, grupo de pares, autonomía, SOP) que esta página da por supuestos.

Con el proveedor de GitHub, ZeroClaw se autentica como una GitHub App y responde con la propia identidad de bot de la aplicación (your-app[bot]), por lo que funciona en cualquier repositorio en el que la aplicación esté instalada. No hay token de acceso personal ni cuenta de usuario compartida.

Con el proveedor Gitea/Forgejo, ZeroClaw se autentica con un token de acceso personal frente a la API compatible con Gitea de la instancia y responde como el propietario del token.

Nota de compilación: el canal Git está incluido en los artefactos de distribución estándar, pero no en la configuración predeterminada ligera de Cargo. Las compilaciones personalizadas desde el código fuente deben añadir channel-git; las compilaciones que deshabiliten las características predeterminadas también deben añadir agent-runtime. La característica channel-git incorpora todos los proveedores de forjas integrados, por lo que un solo binario sirve para todas las forjas compatibles; no hay ningún subconjunto de compilación más pequeño por proveedor que se pueda seleccionar.

Quién puede hablar con el agente

Los remitentes entrantes se filtran contra el conjunto de pares resuelto para el agente vinculado, obtenido de la configuración peer_groups a la que pertenece el agente. La coincidencia elimina el @ inicial y no distingue mayúsculas de minúsculas frente al identificador nativo de remitente del canal. Un conjunto vacío deniega a todos; un conjunto que contiene "*" acepta a cualquiera; en caso contrario, solo se aceptan los pares externos listados (y los agentes pares). Esto es independiente del emparejamiento de la puerta de enlace (gateway.require_pairing), que autentica clientes HTTP/WebSocket, no remitentes de canales de chat.

Un grupo de pares para git establece channel en git, enumera los remitentes permitidos en external_peers (para git, el nombre de usuario de la forja (login) del autor del comentario; ["*"] acepta a cualquiera), opcionalmente nombra agents pares para la distribución entre agentes, una lista de bloqueo ignore y un output_modality (mirror, voice o text). Consulta Peer Groups para la referencia de campos.

Dónde configurar esto:

Cómo funciona

• Polling, no webhooks. El canal consulta la API REST de forge en busca de nuevos issues, pull requests y comentarios mediante un cursor since. El daemon no necesita una URL pública, túnel ni exposición entrante; funciona detrás de NAT.
• Conversaciones acotadas al issue. Cada mensaje en el mismo issue o PR comparte un único hilo de conversación; el agente responde como un comentario en ese issue.
• Respuestas en streaming. El agente publica un comentario borrador y lo edita en el mismo lugar a medida que crece la respuesta (las ediciones están espaciadas ≥ 2 s para respetar los límites de abuso de la forja).
• Reacciones. Las reacciones de acuse de recibo se mapean al conjunto de reacciones del forge (con GitHub: 👀 → eyes, ✅ → +1, ⚠️ → confused, …); los emoji que no se pueden mapear se omiten.
• Inicio en frío. Los eventos creados antes de que se iniciara el daemon nunca se procesan, así que reiniciar no puede reproducir el historial. La contrapartida: los comentarios publicados mientras el daemon estaba inactivo se omiten, así que vuelve a mencionar la app.
• Los comentarios editados se ignoran. Solo los comentarios recién creados y las publicaciones de apertura de issues/PR activan al agente.

Credenciales

Cada proveedor se autentica de forma diferente, y cada uno tiene una guía completa paso a paso:

• GitHub se autentica como una GitHub App (App ID más una clave privada generada). Consulta Creating a GitHub App.
• Gitea / Forgejo se autentican con un token de acceso personal contra la API compatible con Gitea de la instancia. Consulte Crear un token de Gitea / Forgejo (Codeberg).

Configurar

Establece los campos de canal en la superficie que prefieras:

La referencia completa del campo, directamente del esquema:

zeroclaw config set channels.git.<alias>.access_token    # entrada enmascarada, almacenada cifrada

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    # entrada enmascarada, almacenada cifrada

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=

El alias default es la instancia inicial habitual. También es al que apuntan los envíos puntuales: zeroclaw channel send --channel-id git busca específicamente el alias default, así que asigna a la instancia el nombre default, a menos que todos los envíos provengan de un agente vinculado a un alias con otro nombre. Deja repos vacío para consultar todos los repositorios visibles para la credencial, o establécelo en una lista explícita de repositorios para consumir menos cuota de solicitudes. Establece listen_to_bots solo si deben procesarse los comentarios de otras cuentas de bots. Un valor desconocido de provider produce un error claro al iniciar, en lugar de recurrir silenciosamente a otro valor.

La configuración de credenciales difiere según el proveedor y cada uno tiene su propio secreto cifrado; ambas guías lo cubren de principio a fin:

• GitHub: ID de la app más una clave privada. Consulta Creating a GitHub App.
• Gitea / Forgejo: un token de acceso y una URL base de la API. Consulte Crear un token de Gitea / Forgejo (Codeberg).

Eventos y enrutamiento

Más allá de la conversación, el canal normaliza la actividad del repositorio en eventos tipados y enruta cada tipo de evento según la configuración. Enrutar un evento a un sop lo despacha a un Procedimiento Operativo Estándar, un procedimiento determinista y auditable con coincidencia de disparadores y puertas de aprobación. La página Git SOP fan-in detalla exactamente cómo un evento de forge se convierte en una ejecución de SOP.

Tipos de evento conocidos: 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.

• Valores predeterminados. Sin una tabla events, el canal se comporta de forma conversacional: issue_comment.created, issues.opened y pull_request.opened se entregan como mensajes (con restricción por mención, como se describe arriba); todo lo demás se ignora. Los tipos de evento ausentes de una tabla no vacía obtienen los mismos valores predeterminados por tipo: enumerar workflow_run.failed no desactiva la conversación. Una entrada sin message = true ni un sop deshabilita explícitamente ese tipo de evento.
• Enrutar un tipo de evento es suscribirse a él. El canal deriva de la tabla qué extremos de API consultar: los comentarios de revisión, los lanzamientos y las ejecuciones de Actions solo se obtienen cuando sus tipos de evento se enrutan, de modo que un canal no configurado cuesta exactamente lo mismo que antes. GitHub actualmente cubre todos los tipos de evento enumerados; el proveedor Gitea/Forgejo cubre comentarios de incidencias, aperturas de incidencias/PR, transiciones de cierre/fusión de PR, lanzamientos, respuestas, ediciones, eliminaciones y reacciones.
• Enrutamiento de sop. Una ruta de sop emite un evento SOP originado en un canal con el tema git.<alias>:<event_type> y una carga útil JSON estructurada. La entrada de SOP consume el evento enrutado en lugar de entregarlo como chat. Hazlo coincidir en SOP.toml mediante un activador channel que indique el canal y la instancia (channel = "git", alias = "main"); la cadena git.<alias>:<event_type> es el tema del evento generado por el canal, no un campo del activador. Usa una condition opcional para acotarlo aún más, por ejemplo, $.event_type == "pull_request.opened" o $.repo == "octo/repo".
• Puerta de menciones por ruta. La puerta mention_only se aplica a eventos conversacionales en la ruta de mensajes. Los eventos enrutados por sop-routed la omiten: un PR enrutado a pr-triage se captura tanto si el autor mencionó la app como si no. Los eventos de ciclo de vida/CI/lanzamiento no tienen superficie de menciones y nunca están sujetos a esta puerta. La propia actividad de la app siempre se descarta; la actividad de otros bots sigue listen_to_bots; cada entrega pasa la lista de अनुमति del grupo de pares según el inicio de sesión del autor.
• Superficies de respuesta. Los eventos de comentario, issue y PR responden en el hilo de su issue/PR. Los eventos de ejecución de workflow responden en el PR asociado de la ejecución cuando el forge informa uno; de lo contrario, y para los lanzamientos, el destino es el repositorio sin más y el agente no puede responder en la plataforma (redirige esos a un SOP o actúa mediante otras herramientas).
• Columna vertebral de la API de Events (opcional, GitHub). events_backbone = true además consulta /repos/{owner}/{repo}/events con solicitudes condicionales ETag (una solicitud por repo por tic; un repo inactivo responde 304 y cuesta casi nada). Advertencias: el feed tiene un retraso de hasta ~5 minutos, las cargas útiles se recortan y los eventos de Actions nunca aparecen en él: las ejecuciones de workflows siempre usan su endpoint dedicado. Cualquier cosa expuesta tanto por el feed como por un endpoint específico se desduplica, así que es seguro combinarlos. Gitea/Forgejo ignoran esta opción hoy.

Notas de funcionamiento

• Presupuesto de tasa: en GitHub, cada instalación obtiene 5,000 solicitudes/hora; el valor predeterminado conversacional consume 2 solicitudes por repositorio por ciclo de sondeo (5 repos a un intervalo de 30 s ≈ 1,200/hora). Cada familia de endpoints adicional enrutada (comentarios de revisión, versiones, ejecuciones de Actions) añade 1 por repositorio por ciclo, y la base de la API de Events añade 1 solicitud condicional (los 304 en repositorios inactivos son prácticamente gratis). Los límites de tasa de Gitea/Forgejo dependen de la instancia. Ante una respuesta de límite de tasa, el canal aplica retroceso hasta que se reinicia la ventana del límite.
• Muchos repositorios: cuando repos está vacío y la credencial puede ver más de 100 repositorios, solo se consulta la primera página (se registra una advertencia para GitHub). Enumere repos explícitamente en ese caso.

Seguridad

Los issues y los comentarios de PR en repositorios públicos son entradas adversarias. Mantén mention_only = true, restringe los remitentes con un grupo de pares (un conjunto vacío de pares deniega a todos, ["*"] acepta a cualquiera) y mantén autonomía en Supervised o inferior para repositorios expuestos al público. Esta es la misma recomendación que en canales sociales.

Documentos relacionados

• Configura las credenciales: Creando una GitHub App · Creando un token de Gitea / Forgejo (Codeberg)
• Quién puede acceder al agente: Peer Groups
• Qué puede hacer el agente: Seguridad y autonomía · Niveles de autonomía
• Automatización dirigida por eventos: Procedimientos operativos estándar · Git SOP fan-in
• La visión general: Agents · Resumen de canales