Skip to content
Switch branches/tags
Go to file


A GitLab client and webhook receiver for maubot.

Configure plugin

Set up the plugin like any other maubot plugin

Upload the plugin in Maubot Manager, and then create an instance i.e. 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 intance_id.

Set up Gitlab plugin specificities

Once the instance is created, make sure to at least replace the secret with a real password.

For example, you can generate one with:

tr -dc A-Za-z0-9 < /dev/urandom | head -c 32

And save the configuration.

Login to Gitlab account from the bot

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.

    1. Sign in to GitLab.
    1. In the upper-right corner, click your avatar and select Settings.
    1. On the User Settings menu, select Access Tokens.
    1. Choose a name and optional expiry date for the token.
    1. Choose the desired scopes.
    1. Click the Create personal access token button.
    1. 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.


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 PERSONAL_ACCESS_TOKEN

You should now be loggued in your Gitlab account.

Further Gitlab client functionalities

To access further bot's functionalities from Matrix, invoke the bot with !gitlab or !gitlab <command> to get some help:

Usage: !gitlab <subcommand> [...]

    room <subcommand> [...] - Manage the settings for this room.
    server <subcommand> [...] - Manage GitLab Servers.
    alias <subcommand> [...] - Manage Gitlab server aliases.
    issue <subcommand> [...] - Manage GitLab issues.
    commit <subcommand> [...] - View GitLab commits.
    ping - Ping the bot.
    whoami [server URL or alias] - Check who you're logged in as.

Bind repository events to Matrix room (webhooks)

Note: You do not need to be logged-in in order to complete this section.

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

Configure the URL as follow:



  • ${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:!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:


A GitLab client and webhook receiver for maubot.





No packages published