Configuring Gerrit Hooks: Client, Webhook, and Server Hook Methods

Gerrit is a widely used code‑review platform, and users often need to trigger multiple actions automatically after a review event. Hook mechanisms act as bridges between events, allowing actions such as notifications or pipeline triggers to run without manual intervention.

The hook approaches are divided into three categories based on where they are configured: client‑side hooks, webhooks, and server‑side hooks. Client hooks run locally in the repository and cannot affect remote operations, so the focus here is on webhooks and server hooks that intercept remote events.

Webhook configuration

Environment: Gerrit 3.4.0.

1. Add webhook settings in gerrit/review_site/etc/gerrit.config :

[plugin "webhooks"]
connectionTimeout = 3000
socketTimeout = 2500
maxTries = 300
retryInterval = 2000
threadPoolSize = 3

2. Clone the All‑Projects repository and switch to the meta/config branch:

git clone "http://admin@
-:
/a/All-Projects"
cd All-Projects/
git fetch origin refs/meta/config:refs/remotes/origin/meta/config
git checkout meta/config

3. Create webhooks.config in the repository root with the desired events:

[remote "events"]
url = http://11.11.11.111:9000/system_hook/v1/events
maxTries = 3
sslVerify = false
event = patchset-created
event = ref-updated
event = project-created
event = change-merged
event = hashtags-changed

4. Commit the changes and restart Gerrit:

git commit -am "Add webhooks config file"
git push origin meta/config:meta/config

Webhooks can only use the event types and payload formats predefined by Gerrit, which may limit the detail of information available for downstream processing.

Server‑side hook configuration

1. Create a hooks directory under /gerrit/review_site/ :

cd /gerrit/review_site/ & mkdir hooks

2. Add scripts named after the event types (e.g., ref-update , patchset-created ) and implement custom logic. Server hooks are split into Synchronous Hooks (triggered during the event, such as ref-update , submit ) and Asynchronous Hooks (triggered after the event, such as patchset-created , change-merged ).

Server‑side hooks allow full control over subsequent actions and message payloads, making them suitable for scenarios that require custom data or integration with external systems.

Application scenarios

Webhooks are often used to send change notifications to communication tools, while server‑side hooks can invoke CI pipelines, enrich messages with commit details, or push events to message queues like Kafka for further processing.

For example, a ref-update server hook can extract commit information (message, date, uploader, commit ID) and send it via HTTP to an external service.

Summary

Gerrit offers three hook configuration methods; the most commonly used are webhooks and server‑side hooks. Webhooks are limited to Gerrit‑defined events and payloads, whereas server‑side hooks provide customizable actions and payloads, making them preferable when specific data or behavior is required.