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.