Forgejo webhooks receiver for Maubot

A Forgejo webhook receiver for maubot. Works with Codeberg and other Forgejo based servers.

Basic setup

1. Set up the plugin like any other maubot plugin.

   You just have to upload the plugin, and then create an instance i.e. an association of a plugin and a client.

   You have to give this new instance an instance_id / a name, for example "my_forgejo_bot"

2. Register a Forgejo OAuth application to get a client_id and client_secret.

   For example on the Codeberg it's done on: https://codeberg.org/user/settings/applications

   Set the callback URL to https://{maubot_host}/{plugin_base_path}/{instance_id}/auth

   Following our example, if your instance is hosted on maubot.example.com and you kept the default plugin_base_path i.e. _matrix/maubot/plugin, the Forgejo's new OAuth App's form should go like this:

   • Application name: My Forgejo Bot
   • Homepage URL: https://maubot.example.com/
   • Application description: A Maubot Forgejo bot for tracking repositories! Yay!
   • Authorization callback URL: https://maubot.example.com/_matrix/maubot/plugin/my_forgejo_bot/auth

3. Set the client_id and client_secret in maubot.

   Copy these informations from your Forgejo's OAuth App page and paste them in the instance page options.

   client_id: <replace>
   client_secret: <replace>
   

   And save the instance configuration.

4. Use !forgejo login to log in.

   After inviting your bot / client to a matrix channel, use the !fg or !forgejo command to use the github instance.

   Using fg login first is mandatory and needed once per instance.

   The bot will reply with a link leading to your personal Forgejo's allowed OAuth apps page, where you shall grant the necessary rights to the bot OAuth app.

5. Use !forgejo webhook add <owner>/<repo> to add webhooks.

   This will let you see in the current channel all the commits, comments, issues, forks, pull requests, wikis and so on, for that given repository.

   You must have admin rights on the repositories you want to track, as adding webhooks to a repository requires manager access rights to a project.

   Once you create a webhook and track a repository, it will be tracked only in the room from which you are in.

   If you want to limit a scope of the particular webhook, check its properties in Forgejo.

6. Remember: you need a separate instance of the bot for every Forgejo server.

Acknowledgements

This software was written by Dr Serge Victor by re-purposing existing Github Maubot plugin authored by Tulir Asokan and accommodating it to the Forgejo API:

https://mau.dev/maubot/github

License: GNU AFFERO GENERAL PUBLIC LICENSE Version 3