# buzon

This utility listens for webhooks from Gitea or Forgejo and translates them to MQTT.

## What does this do exactly?

Runs as a service that simply listens for messages, converts them into messages
that are suitable for MQTT, and fires them to a configured MQTT-aware endpoint.

## What does the name come from?

Buzón, Spanish for Mailbox.

## How can we use it?

You can deploy the project using poetry or doing a regular pip install with
the requirements file and have fun. If possible, you can also use the packages
available with your distribution. To run, you will need to use uvicorn.

```
uvicorn --host 0.0.0.0 --port 18966 buzon.app:app
```

This service can be hosted either on the same git instance or another instance
(such as a container) entirely. At this time, it does not do authentication nor
secrets.

## Gitea/Forgejo Setup

In your forge, you will need to setup a webhook either at the repository level
or at the system level (site administration -> integrations). Either way, the
setup is as follows:

1. Add a webhook, choose "Gitea" or "Forgejo"
2. Fill in the target URL to where buzon is running and your desired event to handle
(e.g. http://localhost:8989/push-event)
3. HTTP Method is POST
4. POST Content Type is application/json
5. Optional: Secret can be filled, but it makes no difference in operation.
6. Select "Custom Events" and choose the applicable event (e.g. "Push")
7. Optional: You may set a branch filter if desired
8. Add Webhook

At this point, you will need to perform your desired operation to trigger an event.