einar/maubot-osc: Maubot plugin for the Open Build Service.

Maubot plugin for the Open Build Service.

Find a file

Luca Beltrame 34a24e599a [skip ci] Update README		2022-02-12 10:30:58 +01:00
.reuse	Add the .reuse folder	2022-01-23 23:05:25 +01:00
LICENSES	Add public domain license	2022-01-23 22:59:06 +01:00
oscbot	Support for ACLs	2022-02-12 10:19:06 +01:00
.gitignore	REUSE compliance additions	2022-01-23 23:05:13 +01:00
.woodpecker.yml	Fix save path	2022-01-30 00:52:12 +01:00
base-config.yaml	Support for ACLs	2022-02-12 10:19:06 +01:00
maubot.yaml	Bump version	2022-02-12 10:20:14 +01:00
README.md	[skip ci] Update README	2022-02-12 10:30:58 +01:00

README.md

maubot-osc

maubot-osc is a simple maubot plugin to query an Open Build Service 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)

Dependencies

These are in addition to what maubot requires by itself.

lxml
jinja2

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://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 command line utility can generate tokens 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:

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.