Jump to content


From Wikitech
Toolforge tools
GitLab Webhooks
Website https://gitlab-webhooks.toolforge.org/
Description A webhook handler for performing actions on other systems in response to GitLab events.
Keywords gitlab, python, admin
Author(s) Ahmon Dancy, Brennen Bearnes, Bryan Davis
Maintainer(s) (View all)
Source code gitlab
License GNU General Public License 3.0 or later
Issues phab:project/profile/5556/
Admin log Tools.gitlab-webhooks/SAL

gitlab-webhooks listens for GitLab system-level webhook events and performs actions such as posting comments on Phabricator tickets or adding mentions on GitLab merge requests.

How it works

At https://gitlab.wikimedia.org/admin/hooks we have configured a system hook which sends all 4 types of events (repository update, push, tag, merge request) to https://gitlab-webhooks.toolforge.org/hooks. A secret token sent by GitLab in a X-Gitlab-Token header is validated to ensure that events are not spoofed.


gitlab-webhooks examines the events looking for Phabricator bug ids. For each bug id found, a comment is added to the corresponding ticket describing the event. Currently only merge request events are processed.

Bug ids are accepted in the following format: Bug: T12345

There can be multiple Bug: entries per commit message, one per line.

The Bug: T... format is used as it is the historical format used in our Gerrit tooling and commit message standards.

Gitlab Mentions

When gitlab-webhooks receives a merge request event, it adds a mention for anyone with a matching Gitlab-mention template entry in mw:Git/Reviewers. Users who are already participants on the merge request are not re-mentioned.

Server-Sent Events

Tools interested in doing their own processing of collected webhook data can subscribe to a real-time feed rebroadcast by gitlab-webhooks. Events are published as Server-Sent Events (SSE) by the GET /sse/ endpoint. Wikibugs was the first consumer of this data feed.


gitlab-webhooks.toolforge.org is hosted on Toolforge. To administer it you must be listed as a maintainer of the tool. Ask an existing administrator to give you access. When you have access you can do:

$ ssh login.toolforge.org
user@tools-bastion-12:~$ become gitlab-webhooks

The https://gitlab.wikimedia.org/repos/releng/gitlab-webhooks repo runs from a build service managed container. Build a newer container with:

$ toolforge build start https://gitlab.wikimedia.org/repos/releng/gitlab-webhooks

Once a new image has been built, run it with:

$ toolforge webservice restart

The app is configured using environment variables.

$ toolforge envvars list
name                   value
DEBUG                  true
LOG_EVENTS_TO          /data/project/gitlab-webhooks/logs/events.log
SINKS_ENABLED          phabricator,gitlab-mentions,sse


gitlab-webhooks is maintained by the mw:Wikimedia Release Engineering Team.