daladim/gitlab

gitlab

A GitLab client and webhook receiver for maubot.

Usage

Set up the plugin like any other maubot plugin

Upload the plugin in Maubot Manager, and then create an instance (an association of a plugin and a client).

Give this new instance an ID / name, for example my_gitlab_bot. We will refer to this identifier later as instance_id.

Logging into your GitLab account

Create a personal access token, as explained in Gitlab's documentation.

You can create as many personal access tokens as you like from your GitLab profile.

Sign in to GitLab.

In the upper-right corner, click your avatar and select Settings.

On the User Settings menu, select Access Tokens.

Choose a name and optional expiry date for the token.

Choose the desired scopes.

Click the Create personal access token button.

Save the personal access token somewhere safe. If you navigate away or refresh your page, and you did not save the token, you must create a new one.

Source: https://docs.gitlab.com/ee/user/profile/personal_access_tokens.

Invite the bot to a Matrix room.

Assuming the base command to invoke the bot is gitlab, adapt the following command and invoke the bot with:

Warning: Make sure not to enter this command in a public room!

!gitlab server login https://gitlab.example.org PERSONAL_ACCESS_TOKEN

You should now be logged in your Gitlab account. Use !gitlab to view the list of commands and !gitlab <command> to view help for subcommands (e.g. !gitlab webhook).

Setting up webhooks

The instructions below are for adding webhooks manually. You can also simply use !gitlab webhook add <repo>, but that requires logging into the bot using your GitLab token first.

Go to the desired repository's webhooks settings, in Gitlab, under Your repo > Settings > Webhooks.

Configure the URL as follows:

https://${server_name}/${plugin_base_path}/${instance_id}/${instance_path}?room=${room_id}

Where

${server_name} is an ip address or domain name where your Maubot instance is reachable
${base_path} is the base path for plugin endpoint as configured under server.plugin_base_path in config.yaml
${instance_id} is the identifier you previously defined while setting up the plugin instance, here my_gitlab_bot
${instance_path} is the path defined in Maubot Manager > Instances > my_gitlab_bot > path
${room_id} is the Matrix room identifier as defined in its URL, or under Room Settings > Advanced > Internal room identifier

Which gives for example, with the default configuration: https://maubot.example.org/_matrix/maubot/plugin/my_gitlab_bot/webhooks?room=!XXXXXXXXXXXX.

Then configure the secret token as previously defined.

Afterwhile, configure the desired permissions, enable SSL verification if needed and create the webhook.

Finally, test your webhook and fix the configuration until you get a return status like 2xx.

Gitlab webhooks documentation: https://docs.gitlab.com/ee/user/project/integrations/webhooks.html.