GitLab/Webhooks

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

{"name":"gitlab-webhooks","repository":"gitlab","author":"Ahmon Dancy, Brennen Bearnes, Bryan Davis","url":"https://gitlab-webhooks.toolforge.org/","keywords":"gitlab, python, admin","description":"A webhook handler for performing actions on other systems in response to GitLab events."}

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.

Phabricator

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.

Administration

General

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
GITLAB_TOKEN           «REDACTED»
LOG_EVENTS_TO          /data/project/gitlab-webhooks/logs/events.log
PHABRICATOR_TOKEN      «REDACTED»
SINKS_ENABLED          phabricator,gitlab-mentions,sse
SOURCE_TOKEN           «REDACTED»
TOOL_REPLICA_PASSWORD  «REDACTED»
TOOL_REPLICA_USER      s54528
TOOL_TOOLSDB_PASSWORD  «REDACTED»
TOOL_TOOLSDB_USER      s54528

Updating the GitLab token

Create a new token in GitLab

1. Visit https://gitlab.wikimedia.org/admin/users/gitlab-mentions-bot (Requires Gitlab administrator privilege)
2. Click the Impersonate button
3. Visit https://gitlab.wikimedia.org/-/user_settings/personal_access_tokens
4. Click the "Add new token" button and fill in the following information:
   1. Name: gitlab-webhooks-<year> (e.g. gitlab-webhooks-2025)
   2. Expiration: slightly less than one year from today, on a Wednesday
   3. Scopes: api
5. Click the "Create personal access token" button.
6. Copy the created token somewhere you can retrieve it later.
7. Visit https://gitlab.wikimedia.org/admin/impersonation to stop impersonation.

Log into Toolforge to update the token

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

Update the token

$ toolforge envvars create GITLAB_TOKEN
Enter the value of your envvar (Hit Ctrl+C to cancel): <paste token here>

Restart the service to pick up the new token

$ toolforge webservice restart

Testing

Test a GitLab operation that normally results in an IRC mention, such as changing the assignee of a merge request in https://gitlab.wikimedia.org/repos/releng/scap/-/merge_requests

Prepare for next year

Set up a reminder to update the token at least a week before it expires. The reminder should point to this documentation.

Maintainer

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