https://github.com/maubot/github
A GitHub client and webhook receiver for maubot
https://github.com/maubot/github
github github-webhooks matrix-bot maubot
Last synced: about 4 hours ago
JSON representation
A GitHub client and webhook receiver for maubot
- Host: GitHub
- URL: https://github.com/maubot/github
- Owner: maubot
- License: agpl-3.0
- Created: 2018-06-11T10:47:26.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2026-04-05T18:12:58.000Z (about 17 hours ago)
- Last Synced: 2026-04-05T20:20:52.775Z (about 15 hours ago)
- Topics: github, github-webhooks, matrix-bot, maubot
- Language: Python
- Size: 122 KB
- Stars: 55
- Watchers: 6
- Forks: 12
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# github
A GitHub client and webhook receiver for maubot.
## Hosted instance
You can use the instance hosted on maunium.net by talking to
[@github:maunium.net](https://matrix.to/#/@github:maunium.net).
See steps 4 and 5 below.
## 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_github_bot"
2. **[Register a GitHub OAuth application](https://github.com/settings/developers) to get a `client_id` and `client_secret`.**
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 Github's new OAuth App's form should go like this:
* Application name: My Github Bot
* Homepage URL: https://maubot.example.com/
* Application description: A Maubot Github bot for tracking repositories! Yay!
* Authorization callback URL: https://maubot.example.com/_matrix/maubot/plugin/my_github_bot/auth
3. **Set the `client_id` and `client_secret` in maubot.**
Copy these informations from your Github's OAuth App page and paste them in
the instance page options.
```
client_id:
client_secret:
```
And save the instance configuration.
4. **Use `!github login` to log in.**
After inviting your bot / client to a matrix channel, use the `!gh` or
`!github` command to use the github instance.
Using `gh login` first is mandatory and needed once **per instance**.
The bot will reply with a link leading to your personal Github's allowed
OAuth apps page, where you shall grant the necessary rights to the bot
OAuth app.
By default, the bot will request access to all public repos and to add
webhooks. You can control the permissions it wants with some flags:
* `--no-repo` makes it not ask for repo access at all.
Only `!github webhook add` will work, other commands like `!github create`
will not.
* `--no-hook` makes it not ask for webhook access.
`!github webhook add` will not work.
* `--private` makes it ask for private repo access. Necessary if you want to
use the bot to manage private repos.
5. **Use `!github webhook add /` to add webhooks.**
This will let you see in the current channel all the commits, comments,
issues, stars, forks, pull requests, 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**.