GitLab/Webhooks

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