Codeveira› Docs› Gerrit Integration

Gerrit Integration

Connect Codeveira to your Gerrit instance using HTTP credentials and the webhooks plugin. Codeveira listens for ref-updated events and automatically creates a code review for each new commit.

Prerequisites

How Codeveira integrates with Gerrit

Gerrit's integration with Codeveira differs from other platforms because Gerrit is both a code review tool and a Git server. Codeveira sits alongside Gerrit as a post-merge review layer — it creates a new code review after each change lands on a branch, rather than gating the merge itself.

Read-only access via the Gerrit REST API

Codeveira authenticates to Gerrit using HTTP credentials (username + HTTP password — a separate password from your LDAP or browser login). All API calls are strictly read-only. Codeveira uses the Gerrit REST API to:

Gerrit's REST API prefixes all responses with the XSSI protection sequence )]}'\n. Codeveira strips this prefix automatically before parsing — you do not need to configure anything for this.

Event delivery via the webhooks plugin

Gerrit does not send webhooks natively — you need the webhooks plugin. Once the plugin is installed and configured with a ref-updated event pointing at /webhooks/gerrit, Codeveira receives an event every time a branch reference is updated (i.e., a change is merged or a direct push lands). Codeveira then:

  1. Identifies the new commit SHA from the event payload
  2. Fetches the commit data and diff via the Gerrit REST API
  3. Creates a code review in Codeveira for that commit
  4. Notifies assigned reviewers and triggers the AI reviewer (if configured)
Codeveira is complementary to Gerrit, not a replacement. Gerrit handles pre-submit review (mandatory approval before merge). Codeveira provides post-merge review, metrics, AI analysis and a modern UI on top of merged commits. Many teams run both.

The XSSI prefix and authentication quirks

Gerrit's HTTP authentication for the REST API is not the same as your browser login. Gerrit generates a separate HTTP password under Settings → HTTP Credentials. This password is used exclusively for REST API and git-over-HTTPS access. If you get a 401 Unauthorized response, the most common cause is using your LDAP or SSO password here instead of the HTTP password.

1

Generate HTTP credentials in Gerrit

  1. Click your avatar or username in the top-right corner of Gerrit
  2. Go to Settings
  3. Select HTTP Credentials in the left sidebar
  4. Click Generate Password
  5. Note your Gerrit username — it is shown at the top of the Settings page
  6. Copy the generated HTTP password

The credential you will enter in Codeveira combines both values:

username:http_password
# Example:
jsmith:AbCdEfGhIjKlMnOpQrSt
HTTP credentials in Gerrit are different from your LDAP or SSO password. They are generated separately in Settings → HTTP Credentials and used exclusively for REST API and git-over-HTTPS access.
2

Find your project name

Gerrit project names are visible in Gerrit → Browse → Repositories. The name is exactly as displayed — use it verbatim.

Examples of valid project names:

my-project
tools/my-library
org/platform/service

Project names are case-sensitive. Slashes are preserved as-is — they represent the hierarchical namespace within Gerrit, not filesystem paths.

3

Add the repository in Codeveira

  1. Go to Repositories → New Repository
  2. Click the Gerrit platform button
  3. Fill in the fields:
  • Name — display name for this repository in Codeveira
  • Instance URL — base URL of your Gerrit instance, e.g. https://gerrit.example.com
  • Project Name — the Gerrit project name from Step 2, e.g. my-project or tools/my-library
  • Token — username:http_password from Step 1

Click Save. Codeveira will verify access by making a test call to the Gerrit REST API.

4

Configure the webhooks plugin

First verify the webhooks plugin is installed:

ssh -p 29418 admin@gerrit.example.com gerrit plugin ls

If webhooks does not appear in the list, install it by downloading webhooks.jar from the Gerrit CI artifacts for your Gerrit version and placing it in your site's plugins directory:

cp webhooks.jar $GERRIT_SITE/plugins/

Gerrit loads the plugin automatically. No restart is required for plugin hot-deployment.

Next, add the Codeveira remote to $GERRIT_SITE/etc/webhooks.config:

[remote "codeveira"]
  url = https://codeveira.yourdomain.com/webhooks/gerrit
  event = ref-updated
  connectionTimeout = 3000
  socketTimeout = 5000

Reload the plugin to apply the change:

ssh -p 29418 admin@gerrit.example.com gerrit plugin reload webhooks
The ref-updated event fires when a branch is updated — for example, after a change is merged or a direct push lands. Codeveira receives the event and creates a code review for the new commit automatically.

Troubleshooting

Gerrit REST responses contain "XSSI protection" prefix

Gerrit prefixes all REST API responses with )]}'\n to prevent Cross-Site Script Inclusion attacks. Codeveira strips this prefix automatically before parsing the JSON — no action is required on your part.

No code reviews are being created after a push

Check whether the webhooks plugin is delivering events. Enable debug logging by adding the following to $GERRIT_SITE/etc/log4j.properties:

log4j.logger.com.googlesource.gerrit.plugins.webhooks=DEBUG

Then reload the logging configuration or restart Gerrit. Watch the Gerrit error log ($GERRIT_SITE/logs/error_log) for delivery attempts and any HTTP errors returned by Codeveira.

"401 Unauthorized" when Codeveira fetches commit data

You entered your LDAP or browser login password instead of the HTTP password. The HTTP password is generated separately in Gerrit → Settings → HTTP Credentials → Generate Password. Copy the generated value and update the Token field in Codeveira.

The webhooks plugin is not listed in gerrit plugin ls

The plugin is not installed. Download the correct webhooks.jar for your exact Gerrit version from the Gerrit CI artifacts and copy it into $GERRIT_SITE/plugins/. Gerrit hot-deploys plugins automatically — no restart required. If the plugin still does not appear after 30 seconds, check $GERRIT_SITE/logs/error_log for any JAR loading errors (common cause: JAR compiled for a different Gerrit API version).

Webhook delivers events but no code review is created in Codeveira

The most common cause is a mismatch between the Gerrit project name and what is configured in Codeveira. Gerrit project names are case-sensitive and may contain slashes for namespaced projects (e.g. tools/my-library). Verify the exact project name in Gerrit → Browse → Repositories and compare it to the Project Name field in Codeveira → repository settings.

Commits from Gerrit show no diff in Codeveira

When Gerrit submits a change, it may rewrite the commit (e.g. adding a Reviewed-by trailer). The resulting SHA in the ref-updated event is the rewritten commit. Codeveira fetches the diff for this final SHA. If the diff appears empty, verify that the HTTP credentials used by Codeveira have read access to the files in the project — check Gerrit's access rules under Browse → Repositories → [project] → Access.

Evaluating Gerrit vs. Codeveira as your primary review tool? See the full comparison.

Codeveira vs Gerrit → ← All docs