View all connectors

Gerrit

By integrating Gerrit with DX, you can analyze code reviews, changes, projects, and user data. Please refer to the API documentation below and our schema explorer to see what data DX imports—note that DX does not read or access your source code.

Prerequisites

To connect Gerrit to DX, you need:

  • a Gerrit user account with appropriate permissions to access the Gerrit REST API
  • basic authentication credentials (username and password) for the Gerrit instance
  • allowlist DX IP addresses if your Gerrit instance is behind a firewall or has IP restrictions

Setup instructions

Follow the steps below to connect Gerrit to DX.

Data connection

Step 1

Create a Gerrit user account or use an existing account that has the necessary permissions to access:

  • Projects
  • Groups and group members
  • Changes (code reviews)
  • User accounts

To get your authentication credentials:

  1. Log into your Gerrit instance
  2. Navigate to Profile Settings (click on your username in the top right corner)
  3. Go to HTTP Credentials section
  4. Your username is displayed at the top of this section
  5. Click Generate Password to create a new HTTP password for API access
  6. Copy and save both the username and generated password securely

Step 2

  • Navigate to the connections page in DX and select “+ Connection” in the top right.
  • Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.
    • Gerrit Base URL: The base URL of your Gerrit instance (e.g., https://gerrit.example.com)
    • Username: Your Gerrit username
    • Password: Your Gerrit password or HTTP password

API reference

The table below lists the specific API endpoints that are used by DX.

Endpoint Documentation
/a/projects/ Link
/a/groups/ Link
/a/changes/ Link
/a/changes/{change_id}/comments Link
/a/changes/{change_id}/detail Link
/a/groups/{group_name}/members/ Link
/a/accounts/ Link

Errors

The table below lists potential error codes when adding a connection in DX.

Error Description
invalid_credentials Your Gerrit credentials entered are not valid.
invalid_permissions Your Gerrit user account does not have the permissions required by DX.
no_resources DX cannot access any projects or changes in your Gerrit instance.

Curl commands

When connection verification fails

When DX verifies a Gerrit connection, it checks access to projects and changes. If your connection is failing, you can test these endpoints directly using the curl commands below to troubleshoot the issue.

Replace YOUR_GERRIT_URL, YOUR_USERNAME, and YOUR_PASSWORD with your actual values before running these commands.

Authentication:

Use -u YOUR_USERNAME:YOUR_PASSWORD for basic authentication

1. Test Projects Access

This verifies that your credentials can access projects in your Gerrit instance:

curl -u YOUR_USERNAME:YOUR_PASSWORD -H 'Accept: application/json' 'YOUR_GERRIT_URL/a/projects/'

2. Test Groups Access

This verifies that your credentials can access groups:

curl -u YOUR_USERNAME:YOUR_PASSWORD -H 'Accept: application/json' 'YOUR_GERRIT_URL/a/groups/'

3. Test Changes Access

This verifies that your credentials can access changes (code reviews):

curl -u YOUR_USERNAME:YOUR_PASSWORD -H 'Accept: application/json' 'YOUR_GERRIT_URL/a/changes/?q=status:open'

4. Test Accounts Access

This verifies that your credentials can access user account information:

curl -u YOUR_USERNAME:YOUR_PASSWORD -H 'Accept: application/json' 'YOUR_GERRIT_URL/a/accounts/?q=is:active'

If you receive a 401 Unauthorized error, your credentials are invalid. If you receive a 403 Forbidden error, your user account doesn’t have the required permissions. If you receive a 404 Not Found error or empty results, check that your Gerrit base URL is correct and accessible.

Note about Authentication: The -u YOUR_USERNAME:YOUR_PASSWORD flag uses curl’s built-in basic authentication, which automatically handles the Base64 encoding required for Gerrit authentication.