89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
<!--
|
|
SPDX-FileCopyrightText: 2022 Luca Beltrame <lbeltrame@kde.org>
|
|
|
|
SPDX-License-Identifier: CC0-1.0
|
|
-->
|
|
|
|
## maubot-osc
|
|
|
|
|
|
|
|
`maubot-osc` is a simple [maubot](https://maubot.xyz/) plugin to query an [Open Build Service](https://openbuildservice.org/) instance. Basically it replicates a few of the features of the `osc` command line tool used to interact with the OBS.
|
|
|
|
### Features
|
|
|
|
- Query repository status (with links to the latest build log)
|
|
- Trigger rebuild of packages
|
|
- Trigger source service runs
|
|
- Works in E2EE rooms (check the [maubot docs](https://docs.mau.fi/maubot/usage/encryption.html))
|
|
|
|
### Dependencies
|
|
|
|
These are in addition to what maubot requires by itself.
|
|
|
|
- lxml
|
|
- jinja2
|
|
- [cryptocode](https://github.com/gdavid7/cryptocode)
|
|
|
|
### Installation
|
|
|
|
Drop the .mbp file in the plugin section of your maubot web interface.
|
|
Then you need to modify a few configuration parameters for your instance:
|
|
|
|
- `api_url`: the URL to make API requests to the OBS instance. By default it points to the [public OBS instance of the openSUSE project](https://build.opensuse.org) (`https://api.opensuse.org`).
|
|
- `instance_url`: the main URL of the Build Service instance. Defaults to `https://build.opensuse.org`.
|
|
- `username`: A valid username for the instance
|
|
- `password`: A password for the username. Suggestions on how to improve this are welcome.
|
|
- `trigger_token`: An OBS access token with the `runservice` capability. See "Creating tokens" below.
|
|
- `rebuild_token`: An OBS access token with the `rebuild` capability. See "Creating tokens" below.
|
|
- `secret`: A random string used to encrypt the password in the configuration file.
|
|
- `acl`: User IDs (`@user:homeserver.com`) which are allowed to interact with the bot. See "Access control lists" below.
|
|
|
|
### Creating tokens
|
|
|
|
The [`osc`](https://en.opensuse.org/openSUSE:OSC) command line utility can generate [tokens](https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.authorization.token.html#id-1.5.10.18.4) needed for some operations (rebuild packages and triggering source services). As far as I know, there is no way to have a token with more than one supported operation, so you'll need to generate two.
|
|
|
|
This assumes you have already configured `osc` to connect to your OBS instance of interest. Refer to the OSC wiki (linked above) for more information.
|
|
|
|
Generate a token with the `rebuild` capability:
|
|
|
|
```
|
|
osc token --create --operation rebuild
|
|
```
|
|
|
|
And one with the `runservice` capability (default):
|
|
|
|
```
|
|
osc token --create
|
|
```
|
|
|
|
Save both tokens in the configuration. Should you need to, you can view them later by running `osc token` with no arguments.
|
|
|
|
### Usage
|
|
|
|
Make sure your bot instance is in a room (refer to the maubot docs for how) and then type `!osc help` for help.
|
|
|
|
### Access control lists (ACLs)
|
|
|
|
By default, no user is allowed to perform any operation. You need to change the `acl` section of the configuration to add user IDs (`@user:homeserver.com`) allowed to interact with the bot. Users in the `admin` list have full powers over the bot, while users in the `user` list can only perform read-only (e.g. status querying) actions.
|
|
|
|
This example shows how it works in practice:
|
|
|
|
```yaml
|
|
acl:
|
|
admin:
|
|
# Fred and Sue will be able to perform all commands
|
|
- @fred:myhome.com
|
|
- @sue:otherserver.com
|
|
user:
|
|
# Phil will only be able to run read-only (status, etc.) commands
|
|
- @phil:elsewhere.com
|
|
```
|
|
|
|
### Notice
|
|
|
|
I made this for my own use. Don't expect high quality code or a lot of polish.
|
|
|
|
### License
|
|
|
|
This project is licensed under the Affero GNU General Public License, version 3.0, or (at your option) any later version.
|