Webhooks y Migracion

Los webhooks permiten que Forgejo notifique a servicios externos cuando ocurren eventos en un repositorio. La migracion facilita traer repositorios completos desde otras plataformas, incluyendo historial, issues y pull requests.

---

Webhooks

Configuracion basica

Los webhooks se configuran por repositorio en Settings > Webhooks > Add Webhook.

Los campos principales son:

• Target URL: endpoint que recibira las peticiones POST
• HTTP Method: POST (unico soportado)
• Content Type: application/json o application/x-www-form-urlencoded
• Secret: cadena secreta para verificar la firma del payload
• Trigger On: eventos que disparan el webhook

Eventos disponibles

Evento	Cuando se dispara
Push	Al hacer git push a cualquier rama
Create	Al crear una rama o tag
Delete	Al eliminar una rama o tag
Issues	Al abrir, cerrar, editar o comentar un issue
Pull Request	Al abrir, cerrar, fusionar o comentar un PR
Release	Al crear o editar una release
Fork	Al hacer fork del repositorio
Wiki	Al editar la wiki

Formatos soportados

• Forgejo: payload JSON propio (el mas completo)
• Slack: formato compatible con Incoming Webhooks de Slack
• Discord: formato compatible con Discord Webhooks
• Microsoft Teams: formato de tarjeta adaptable
• Telegram: envia mensajes al bot configurado
• Matrix: notificaciones en salas Matrix

Verificar la firma

Cuando se configura un Secret, Forgejo incluye el header X-Forgejo-Signature con un HMAC-SHA256 del payload. Verificar este header garantiza que la peticion viene de Forgejo:

import hmac
import hashlib

def verificar_firma(payload: bytes, secret: str, firma_recibida: str) -> bool:
    firma_esperada = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(firma_esperada, firma_recibida)

Historial de entregas

En Settings > Webhooks > (nombre del webhook) se puede ver el historial completo de entregas: request enviado, response recibido, codigo HTTP y tiempo de respuesta. Desde ahi se pueden reenviar entregas fallidas.

---

Ejemplo: notificacion a Slack en cada push

En Slack, crea un Incoming Webhook en tu workspace y obtiene la URL.

En Forgejo, agrega un webhook con:

• Target URL: https://hooks.slack.com/services/T.../B.../xxx
• Content Type: application/json
• Trigger On: Push

Selecciona el formato Slack y Forgejo enviara automaticamente un mensaje con el autor, rama y commits del push.

Si necesitas un formato personalizado, usa una URL intermedia (por ejemplo un Cloud Function o un servidor propio) que reciba el payload de Forgejo y lo transforme antes de enviarlo a Slack.

---

Migracion desde GitHub

Desde la interfaz web, ve a + > New Migration > GitHub.

Completa el formulario:

Campo	Descripcion
Clone URL	URL del repositorio en GitHub
Access Token	Token de GitHub con permisos repo
Owner	Tu usuario o una organizacion en Forgejo
Repository Name	Nombre del nuevo repositorio

Opciones de migracion disponibles:

• Wikis
• Labels
• Milestones
• Issues (con comentarios)
• Pull Requests (con comentarios y revisiones)
• Releases (con assets)
• Git LFS objects

La migracion es asincrona. Puedes ver el progreso desde la pagina del repositorio.

---

Migracion desde GitLab

El proceso es identico al de GitHub. Selecciona GitLab como origen.

Necesitas un token de GitLab con scope read_api y read_repository. Si el repositorio es privado, tambien necesitas read_user.

Las migraciones de GitLab soportan:

• Issues y comentarios
• Labels y milestones
• Merge Requests (se convierten en Pull Requests)
• Releases

---

Migracion desde Bitbucket

Selecciona Bitbucket como origen. Limitaciones conocidas:

• Los comentarios en linea de Pull Requests no siempre se migran correctamente
• Los attachments de issues no se importan
• Los permisos de repositorio no se transfieren
• Las pipelines de CI no se migran

Para Bitbucket Cloud se recomienda generar un App Password en Account Settings > App Passwords con permisos de lectura en repositorios e issues.

---

Mirror Push: mantener un espejo en GitHub

El mirror push permite que Forgejo sincronice automaticamente los cambios de un repositorio hacia otro servidor externo. Util para mantener un espejo publico en GitHub de un repositorio que vive en Forgejo.

Configuracion en Settings > Mirror Settings:

1. Activa Push Mirrors
2. Agrega la URL del repositorio destino en GitHub:

   https://usuario:[email protected]/usuario/mi-repo.git

3. Define el intervalo de sincronizacion (minimo 10 minutos)
4. Guarda y haz click en Synchronize Now para verificar

Cada push a Forgejo dispara automaticamente la sincronizacion al espejo.

Para un token de GitHub, genera uno en Settings > Developer Settings > Personal Access Tokens con permisos repo.

---

Mirror Pull: importar un repositorio externo

Si quieres que Forgejo mantenga una copia actualizada de un repositorio externo:

1. Ve a + > New Migration
2. Selecciona la plataforma origen
3. Activa la opcion This repository will be a mirror

Forgejo sincronizara automaticamente segun el intervalo configurado en app.ini:

[mirror]
DEFAULT_INTERVAL = 8h
MIN_INTERVAL = 10m

---

Siguiente: Capitulo 20: Bases de Datos