Creando una GitHub App

El canal de Git con provider = "github" se autentica como una GitHub App, no como un usuario. La app tiene su propia identidad de bot (your-app[bot]), sus propios permisos y funciona en cada repositorio en el que está instalada. Esta página recorre la creación única de la app y asigna cada valor a la configuración del canal.

Funciona tanto para una cuenta personal como para una organización: la única diferencia es dónde reside la app y quién puede instalarla.

Documentación oficial: la propia documentación de GitHub, Registering a GitHub App y Managing private keys for GitHub Apps, son la referencia principal para todo lo que aparece en esta página.

1. Crea la app

GitHub → Settings → Developer settings → GitHub Apps → New GitHub App.

• Aplicación personal: créala en tus propios Developer settings.
• Aplicación de Org: cambia primero a la org (Settings → Developer settings en la organización), para que la org sea la propietaria de la app y los administradores de la org puedan gestionarla.

Completar:

1. Nombre y URL de la página principal: cualquier URL válida; la app nunca sirve tráfico web.
2. Webhook → Active: desmárcalo. El canal consulta la API REST; no recibe webhooks y no necesita una URL pública.
3. Permisos del repositorio: concede exactamente lo que usa el canal y nada más:
   • Problemas: Lectura y escritura
   • Pull requests: Leer y escribir
   • Contenido: Solo lectura (necesario para los listados de archivos de PR y las versiones)
   • Metadatos: Solo lectura (obligatorio; autoseleccionado)
   • Acciones: Solo lectura, solo si enrutas eventos workflow_run.*
   • Deje todos los demás permisos en Sin acceso.
4. ¿Dónde se puede instalar esta aplicación?: “Solo en esta cuenta” está bien para una configuración personal o de una sola organización.

Haz clic en Create GitHub App.

2. Recopila las dos credenciales

En la página de configuración de la app después de la creación:

• ID de la aplicación: se muestra cerca de la parte superior. Esto es app_id.
• Claves privadas → Generar una clave privada. GitHub descarga un único .pem (RS256). Esta es tu clave de firma; GitHub solo conserva la parte pública. Pegas su contenido en private_key; el archivo .pem en sí no se referencia en tiempo de ejecución, así que una vez que la clave se almacena puedes eliminar la descarga.

3. Instala la aplicación

Configuración de la app → Install App → elige tu cuenta o tu organización → selecciona All repositories o una selección específica. La instalación es lo que otorga a la app acceso a los repositorios; sin ella, la app puede autenticarse pero no ve nada.

Si la app está instalada en exactamente una cuenta, puedes dejar installation_id sin establecer: el canal enumera las instalaciones en el primer uso y selecciona automáticamente la única, fallando de inmediato si encuentra cero o varias. Establece installation_id explícitamente solo cuando la app tenga varias instalaciones (un alias de canal sirve a una instalación).

4. Mapea en la configuración

Establece cada campo de abajo en la superficie que prefieras. La clave privada es un secreto cifrado y obtiene su propio widget enmascarado; el resto son campos normales.

provider: establecer en github.

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

app_id: el ID de la aplicación del paso 2.

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

private_key: el PEM del paso 2. Vive incrustado en el único almacén de configuración cifrado; no hay un archivo de clave separado en disco que proteger. Pegue el PEM completo, incluidas las líneas BEGIN/END; el panel lo muestra como un campo multilinea enmascarado.

channels.git.<alias>.private_key es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Configúralo mediante una de estas opciones, que cifran al escribir:

zeroclaw config set channels.git.<alias>.private_key    # solicita entrada enmascarada, almacena cifrado

repos: la lista owner/repo a vigilar. Déjalo vacío para sondear todos los repos que la instalación pueda ver.

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

installation_id: opcional, solo cuando la app tiene varias instalaciones (paso 3). Con una sola instalación, déjalo sin establecer y el canal se selecciona automáticamente.

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

Para la referencia completa de los campos, consulta la página del canal Git.

5. Verificar

El canal de Git se incluye en los artefactos de distribución estándar, pero no en la configuración predeterminada reducida de Cargo. Para una compilación personalizada desde el código fuente, incluye channel-git (y agent-runtime al deshabilitar las características predeterminadas):

cargo build --features channel-git

channel-git incorpora todos los proveedores de forge cableados en una sola compilación; no existe un subconjunto más pequeño por proveedor, y compilar una característica provider-* aislada sin channel-git no registra el canal.

Al iniciarse, el canal genera un JWT de la app, lo intercambia por un token de instalación y resuelve su propio inicio de sesión del bot. Un pull_request.opened o una mención @ de la app en un issue ahora debería llegar al agente. Si el inicio falla con un error de clave privada faltante, private_key no está definido o está vacío; si falla con un error de instalación, la app tiene cero o varias instalaciones, así que establece installation_id. Consulta la página del canal Git para el enrutamiento de eventos, la vinculación de grupos de pares y las notas de operación.

Próximos pasos

• Volver al canal: Git channel para enrutamiento de eventos, streaming, presupuesto de tasa y seguridad.
• Restringir quién puede acceder al agente: Peer Groups.
• Automatiza acciones a partir de eventos de forge: Procedimientos Operativos Estándar y el Git SOP fan-in.
• ¿Nuevo en ZeroClaw? Quickstart y Concepts.