Plugin — Gitea

El plugin de Gitea escucha eventos de issues y pull requests desde repositorios autohospedados. Valida la autenticidad de cada request mediante firma HMAC SHA-256 antes de procesar el payload.

Mecanismo: Webhook · Autenticación: HMAC SHA-256 · Eventos soportados: issues, pull_request

Endpoint del webhook

Propiedad	Valor
Método	`POST`
Ruta	`/plugins/gitea/webhook/{plugin_id}/`

Parámetro	Ubicación	Descripción
`plugin_id`	Path	ID del `PluginConfig` registrado para esta instancia Gitea.
`X-Gitea-Event`	Header	Tipo de evento enviado por Gitea: `issues` o `pull_request`.
`X-Gitea-Signature`	Header	Firma HMAC SHA-256 del body. Formato: `sha256=<hex>`.

Configuración paso a paso

Registrar el PluginConfig en Joe

from apps.common.models import PluginConfig

config = PluginConfig(
    usuario=user,
    servicio="gitea",
    identificador="pogit.pedroospino.net",
    metadatos={"webhook_secret": "mi_secret_hmac_seguro"},
)
# Gitea no requiere un token OAuth para solo recibir webhooks,
# pero puedes guardar un token de acceso personal si necesitas
# que Joe también realice acciones en la API de Gitea:
config.set_token("")   # Dejar vacío si solo se reciben webhooks
config.save()
# Anota el ID: config.pk → ej. 5

Agregar el webhook en Gitea

En tu repositorio de Gitea: Settings → Webhooks → Add Webhook → Gitea

Campo	Valor
Target URL	`https://joe.pedroospino.net/plugins/gitea/webhook/5/`
HTTP Method	`POST`
Content Type	`application/json`
Secret	El mismo valor que `webhook_secret` en metadatos
Trigger On	Issues, Pull Requests
Active	✓

Probar el webhook
Desde la misma página de configuración en Gitea, usa el botón "Test Delivery" para enviar un evento de prueba y verificar que Joe responde con HTTP 200.

Flujo de un issue entrante

Evento: `issues` — action `opened`

Gitea envía el payload firmado al endpoint de Joe.
Joe valida la firma: sha256=HMAC(secret, body).
Se deserializa el payload como GiteaIssueEvent.
Se crea una tarea con tipo=gitea_issue, estado=abierto, URL externa del issue.

Evento: `issues` — action `closed` / `reopened`

Joe busca tareas existentes por metadatos_extra.issue_number + repo.
Actualiza el campo estado: terminado si se cerró, abierto si se reabrió.

Evento: `pull_request` — action `opened`

Se crea una tarea con tipo=gitea_pr, estado=abierto.
Solo se procesa la acción opened. Otros estados de PR se ignoran en V1.

Campos en `metadatos_extra` de la tarea

Para issues (`gitea_issue`)

Campo	Descripción
`repo`	Nombre completo del repo: `owner/repo`
`issue_number`	Número del issue en Gitea. Usado para sincronizar estado.
`sender`	Username del usuario que abrió el issue.
`labels`	Lista de etiquetas del issue al momento de creación.
`plugin_id`	ID del PluginConfig que procesó el evento.

Para pull requests (`gitea_pr`)

Campo	Descripción
`repo`	Nombre completo del repo: `owner/repo`
`pr_number`	Número del PR en Gitea.
`sender`	Username del autor del PR.
`plugin_id`	ID del PluginConfig que procesó el evento.

Validación de firma (modo dev)

Sin secret en dev: Si metadatos.webhook_secret está vacío, la validación de firma se omite automáticamente. Esto facilita el desarrollo local, pero nunca debe usarse en producción.

Campos del PluginConfig para Gitea

Campo	Valor esperado
`servicio`	`"gitea"`
`identificador`	Hostname de tu instancia: `pogit.pedroospino.net`
`token_cifrado`	Token de acceso personal (opcional, solo si Joe necesita actuar en la API de Gitea)
`metadatos.webhook_secret`	String secreto compartido con Gitea para firmar los webhooks.

The Gitea plugin listens to issue and pull request events from self-hosted repositories. It validates the authenticity of each request using HMAC SHA-256 signature before processing the payload.

Mechanism: Webhook · Authentication: HMAC SHA-256 · Supported events: issues, pull_request

Webhook endpoint

Property	Value
Method	`POST`
Path	`/plugins/gitea/webhook/{plugin_id}/`

Parameter	Location	Description
`plugin_id`	Path	ID of the `PluginConfig` registered for this Gitea instance.
`X-Gitea-Event`	Header	Event type sent by Gitea: `issues` or `pull_request`.
`X-Gitea-Signature`	Header	HMAC SHA-256 signature of the body. Format: `sha256=<hex>`.

Step-by-step configuration

Register the PluginConfig in Joe

from apps.common.models import PluginConfig

config = PluginConfig(
    usuario=user,
    servicio="gitea",
    identificador="pogit.pedroospino.net",
    metadatos={"webhook_secret": "my_secure_hmac_secret"},
)
config.set_token("")   # Leave empty if only receiving webhooks
config.save()
# Note the ID: config.pk → e.g. 5

Add the webhook in Gitea

In your Gitea repository: Settings → Webhooks → Add Webhook → Gitea

Field	Value
Target URL	`https://joe.pedroospino.net/plugins/gitea/webhook/5/`
HTTP Method	`POST`
Content Type	`application/json`
Secret	Same value as `webhook_secret` in metadatos
Trigger On	Issues, Pull Requests
Active	✓

Test the webhook
From the same configuration page in Gitea, use the "Test Delivery" button to send a test event and verify that Joe responds with HTTP 200.

Incoming issue flow

Event: `issues` — action `opened`

Gitea sends the signed payload to Joe's endpoint.
Joe validates the signature: sha256=HMAC(secret, body).
The payload is deserialized as GiteaIssueEvent.
A task is created with tipo=gitea_issue, estado=abierto, and the issue's external URL.

Event: `issues` — action `closed` / `reopened`

Joe searches for existing tasks by metadatos_extra.issue_number + repo.
Updates the estado field: terminado if closed, abierto if reopened.

Event: `pull_request` — action `opened`

A task is created with tipo=gitea_pr, estado=abierto.
Only the opened action is processed. Other PR states are ignored in V1.

Signature validation (dev mode)

No secret in dev: If metadatos.webhook_secret is empty, signature validation is automatically skipped. This facilitates local development, but must never be used in production.

PluginConfig fields for Gitea

Field	Expected value
`servicio`	`"gitea"`
`identificador`	Your instance hostname: `pogit.pedroospino.net`
`token_cifrado`	Personal access token (optional, only if Joe needs to act on Gitea's API)
`metadatos.webhook_secret`	Secret string shared with Gitea to sign webhooks.

Plugin — Gitea

Plugin — Gitea

Endpoint del webhook

Configuración paso a paso

Flujo de un issue entrante

Evento: issues — action opened

Evento: issues — action closed / reopened

Evento: pull_request — action opened

Campos en metadatos_extra de la tarea

Para issues (gitea_issue)

Para pull requests (gitea_pr)

Validación de firma (modo dev)

Campos del PluginConfig para Gitea

Webhook endpoint

Step-by-step configuration

Incoming issue flow

Event: issues — action opened

Event: issues — action closed / reopened

Event: pull_request — action opened

Signature validation (dev mode)

PluginConfig fields for Gitea

Evento: `issues` — action `opened`

Evento: `issues` — action `closed` / `reopened`

Evento: `pull_request` — action `opened`

Campos en `metadatos_extra` de la tarea

Para issues (`gitea_issue`)

Para pull requests (`gitea_pr`)

Event: `issues` — action `opened`

Event: `issues` — action `closed` / `reopened`

Event: `pull_request` — action `opened`