Creando un token de Gitea / Forgejo (Codeberg)

El canal de Git con provider = "gitea" o provider = "forgejo" se autentica con un token de acceso personal frente a la API REST compatible con Gitea de la instancia, y responde como propietario del token. Ambos proveedores comparten una única implementación interna; la única diferencia real con GitHub es que no hay una app, solo un token y una URL base de API explícita.

Los ejemplos a continuación usan Codeberg (una instancia pública de Forgejo). Para un Gitea o Forgejo autohospedado, sustituya su propio host.

Documentación oficial: El alcance del token de acceso de Forgejo es la referencia upstream para los alcances de token; en Codeberg, sigue Generando un token de acceso. Las instancias de Gitea exponen la misma interfaz de tokens.

1. Usa una cuenta de bot dedicada

Crea el token en una cuenta de bot separada, no en tu cuenta de operador. El canal ignora su propia actividad: si el propietario del token también es la persona que @menciona la app, esos mensajes se omiten silenciosamente. Una cuenta dedicada mantiene separadas las respuestas del bot y tus propios comentarios.

En Codeberg, registra una segunda cuenta normal para el bot e invítala a los repositorios de destino (o a la organización) con acceso de escritura.

2. Genera el token

Como la cuenta del bot: Configuración → Aplicaciones → Administrar tokens de acceso (Codeberg: https://codeberg.org/user/settings/applications).

1. Asigna un nombre al token (por ejemplo, zeroclaw).
2. Selecciona ámbitos. El canal necesita, como mínimo:
   • read:user: el canal resuelve su propia identidad de bot desde /user al inicio.
   • Repositorio lectura más escritura de issue/PR. En Forgejo/Codeberg, los ámbitos se agrupan en read:repository + write:repository y read:issue + write:issue. Si la interfaz solo ofrece ámbitos generales repository / issue, marca esos.
3. Genera el token y cópialo. Se muestra una sola vez.

El token necesita acceso de lectura al repositorio y acceso de escritura a comentarios de incidencias/PR para respuestas y reacciones. No concedas nada más allá de lo que requieran los repositorios de destino.

3. Encuentra la URL base de la API

Esta es la parte sin valor predeterminado. El canal falla de forma cerrada al inicio si api_base_url no está configurado, porque cada solicitud lleva el token como credencial bearer y no adivinará un host al que enviarlo.

El valor es la raíz de la instancia más /api/v1:

• Codeberg: https://codeberg.org/api/v1
• Servicio público de Gitea: https://gitea.com/api/v1
• Self-hosted: https://git.example.org/api/v1

4. Mapea en la configuración

Establece cada campo a continuación en la superficie que prefieras. El token de acceso es un secreto cifrado y tiene su propio widget enmascarado; el resto son campos normales.

provider: gitea para una instancia de Gitea, forgejo para una instancia de Forgejo (incluido Codeberg). Se comportan de forma idéntica, y un valor desconocido produce un error claro al iniciar en lugar de una alternativa silenciosa.

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

api_base_url: la raíz de la instancia más /api/v1 (paso 3). Obligatorio; el inicio falla de forma cerrada sin él.

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

access_token: el token del paso 2.

channels.git.<alias>.access_token es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Establécelo a través de una de estas opciones, que cifran al escribir:

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

repos: la lista owner/repo para vigilar. Déjalo vacío para consultar cada repositorio que el token pueda ver.

zeroclaw config set channels.git.<alias>.repos <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 llama a /user para resolver su inicio de sesión de bot, registra una línea IDENTITY OK y comienza a hacer polling. Menciona al bot con @ en un issue o PR de un repositorio configurado para confirmar que responde. Si el inicio falla y se queja de api_base_url, falta la URL base o está en blanco. Consulta la página del canal Git para ver el enrutamiento de eventos, la vinculación al grupo de pares y las notas de funcionamiento.

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.