Gerrit

Supported on Enterprise plans.

Available via the Web app.

This feature is in beta and might change in the future.

A Gerrit instance can be connected to Sourcegraph as follows:

Configure Gerrit as a code host connection

  1. In the Site Admin settings area, select Manage code hosts from the options on the left and select the Add code host option. The Manage code hosts section in the Site Admin settings area.
  2. On the following screen, select Gerrit as the code host of choice. Gerrit as a code host option in the list
  3. Next you will have to provide a configuration for the Gerrit code host connection. Here is an example configuration:
JSON
{
  "url": "https://gerrit.example.com/", // Be sure to add a trailing slash
  "username": "<username>",
  "password": "<password>",
  "projects": [ // If not set, all projects on the Gerrit instance will be mirrored
    "docs",
    "kubernetes/kubernetes"
  ],
  "exclude": [ // If not set, no repositories will be excluded. Takes precedence over the `projects` option
    { "name": "docs" } // Despite "docs" being specified in "projects", this setting will override it and exclude the "docs" project
  ],
  "authorization": {} // Marks all repositories as private. Users will be required to present valid Gerrit HTTP credentials in order to view repositories
}
  1. The provided username and password must be the HTTP credentials of an account on Gerrit that has access to all the repositories that need to be cloned. See the Gerrit HTTP documentation for details on how to generate HTTP credentials.
  2. Select Add Repositories to create the connection. Sourcegraph will start mirroring the specified projects.

If you added the "authorization": {} option to the configuration, and this is the first Gerrit code host connection you have created for this Gerrit instance, you might see a warning like this: Warning indicating that an authentication provider is required for a code host connection

Simply follow the steps in the next section to configure a Gerrit authentication provider.

Clone using SSH

To clone using SSH, provide "gitSSHCredential" in the configuration:

JSON
{
  "url": "https://gerrit.example.com/",
  "username": "<username>",
  "password": "<password>",
  "projects": [
    "docs",
    "kubernetes/kubernetes"
  ],
  "gitSSHCredential": {
    "privateKey": "..." // base64 encoded private key that will be used for cloning
  },
  "authorization": {}
}

Add Gerrit as an authentication provider

If the "authorization": {} option has been set on a Gerrit code host connection, a Gerrit authentication provider will be required so that authroized users are able to search for and browse the code mirrored by that code host connection.

  1. In the Site Admin settings area, select Site configuration from the options on the left.
  2. Add a Gerrit configuration to the list of "auth.providers". Add a Gerrit configuration to the list of configured authentication providers
  3. Here is an example configuration:
JSON
{
  "type": "gerrit",
  "url": "https://gerrit.example.com/" // This must match the URL of the code host connection. Be sure to add a trailing slash
}
  1. Save the configuration. If there was a warning at the top of the page, it should now disappear.

Users should now be able to authenticate their Sourcegraph accounts using their Gerrit HTTP credentials.

Have users authenticate their Sourcegraph accounts using their Gerrit HTTP credentials

After configuring Gerrit as a code host connection and adding Gerrit as an authentication provider, users will be able to authenticate their Sourcegraph accounts using their Gerrit HTTP credentials:

As a user:

  1. Visit your user settings page and select Account security from the options on the left. A user's Account security page
  2. Gerrit should appear in the list of accounts you are able to connect. If it does not appear, try refreshing the page.
  3. Select the Add option next to Gerrit.
  4. Provide your Gerrit username and HTTP password. If you are unsure of how to generate an HTTP password, see the Gerrit HTTP documentation.
  5. Once your Gerrit credentials are verified, you'll be able to view your private Gerrit projects within Sourcegraph! If you cannot immediately see any projects you should have access to, try giving it some time, as it can take a while for your Gerrit permissions to reflect on Sourcegraph if there is a high volume of users on the system.

Configuration

Gerrit connections support the following configuration options, which are specified in the JSON editor in the site admin "Manage code hosts" area.

admin/code_hosts/gerrit.schema.json

JSON
{
	// If non-null, enforces Gerrit repository permissions. This requires that there is an item in the [site configuration json](https://sourcegraph.com/docs/admin/config/site_config#auth-providers) `auth.providers` field, of type "gerrit" with the same `url` field as specified in this `GerritConnection`.
	"authorization": null,
 
	// The password associated with the Gerrit username used for authentication.
	"password": null,
 
	// An array of project strings specifying which Gerrit projects to mirror on Sourcegraph. If empty, all projects will be mirrored.
	"projects": null,
	// Other example values:
	// - ["name","owner/name"]
	// - [
	//     "docs",
	//     "kubernetes/kubernetes",
	//     "golang/go",
	//     "facebook/react"
	//   ]
 
	// A list of repositories to never mirror from this Gerrit instance. Takes precedence over \"projects\" configuration.
	//
	// Supports excluding by name ({"name": "owner/name"})
	"exclude": null,
	// Other example values:
	// - [
	//     {
	//       "name": "docs"
	//     },
	//     {
	//       "name": "php/php-src"
	//     }
	//   ]
 
	// URL of a Gerrit instance, such as https://gerrit.example.com.
	"url": null,
	// Other example values:
	// - "https://gerrit.example.com"
 
	// A username for authentication withe the Gerrit code host.
	"username": null
}

Configuration Notes

HTTP Credentials Setup

Gerrit requires HTTP credentials for API access and repository cloning:

  • Generate credentials in Gerrit web UI under Settings → HTTP Credentials
  • The configured user must have access to all repositories that need to be mirrored
  • HTTP credentials are separate from Gerrit user passwords

Project vs Repository Mirroring

Gerrit organizes code in projects, not individual repositories:

  • Use "projects": ["docs", "kubernetes/kubernetes"] to specify which projects to mirror
  • If projects is empty or omitted, all projects on the Gerrit instance will be mirrored
  • Project names follow the format shown in Gerrit's project list

Authentication and Authorization

The authorization field controls access to private repositories:

  • Include "authorization": {} to mark all repositories as private
  • Requires corresponding Gerrit authentication provider in site configuration
  • Users must authenticate with their Gerrit HTTP credentials to access repositories

Security Considerations

Access Control

  • Private Repository Access: Enable authorization to enforce Gerrit permissions in Sourcegraph
  • Authentication Provider Required: Configure Gerrit as an auth provider when using authorization
  • User Permission Sync: Sourcegraph respects Gerrit's project-level access controls

Credential Management

  • Service Account: Use a dedicated Gerrit account with appropriate permissions for mirroring
  • HTTP Credentials: Store HTTP username and password securely using Sourcegraph's secret management
  • SSH Keys: For SSH cloning, ensure private keys are base64 encoded and securely stored

Network Security

  • HTTPS Communication: Always use HTTPS URLs for Gerrit connections
  • SSH Configuration: If using SSH, properly manage SSH keys and known_hosts configuration
  • Firewall Rules: Ensure Sourcegraph can reach Gerrit endpoints on required ports

Permission Synchronization

  • Real-time Sync: User permissions may take time to synchronize from Gerrit
  • Access Validation: Users without proper Gerrit access will be denied repository access
  • Project-Level Control: Permissions are enforced at the Gerrit project level

Common Examples

Basic Public Repository Setup

JSON
{
  "url": "https://gerrit.example.com/",
  "username": "sourcegraph-service",
  "password": "http-credentials-password",
  "projects": [
    "public-docs",
    "open-source-project"
  ]
}

Private Repository with Authorization

JSON
{
  "url": "https://gerrit.example.com/",
  "username": "sourcegraph-service", 
  "password": "http-credentials-password",
  "projects": [
    "internal/backend",
    "internal/frontend",
    "shared/libraries"
  ],
  "authorization": {}
}

SSH-Based Cloning

JSON
{
  "url": "https://gerrit.example.com/",
  "username": "sourcegraph-service",
  "password": "http-credentials-password", 
  "projects": [
    "docs",
    "kubernetes/kubernetes"
  ],
  "gitSSHCredential": {
    "privateKey": "LS0tLS1CRUdJTi5CRUdJTiBPUE..."
  },
  "authorization": {}
}

Selective Project Exclusion

JSON
{
  "url": "https://gerrit.example.com/",
  "username": "sourcegraph-service",
  "password": "http-credentials-password",
  "projects": [
    "active-project-1",
    "active-project-2", 
    "legacy-project"
  ],
  "exclude": [
    {"name": "legacy-project"}
  ]
}

Best Practices

Setup and Configuration

  • Service Account: Create a dedicated Gerrit account for Sourcegraph with minimal required permissions
  • Project Selection: Be selective about which projects to mirror to avoid unnecessary resource usage
  • URL Consistency: Ensure the Gerrit URL in code host config matches the auth provider URL exactly

Authentication Management

  • Auth Provider Setup: Always configure Gerrit authentication provider when using authorization
  • User Onboarding: Educate users on how to connect their Gerrit accounts to Sourcegraph
  • Permission Testing: Test that users can access appropriate repositories after connecting accounts

Performance Optimization

  • Selective Mirroring: Use specific project lists rather than mirroring all projects
  • Exclusion Patterns: Use exclude rules to skip archived or inactive projects
  • Connection Monitoring: Monitor Gerrit API usage and response times

Operational Considerations

  • Credential Rotation: Implement regular rotation of HTTP credentials
  • Permission Sync Monitoring: Monitor user permission synchronization status
  • Project Changes: Update project lists when new projects are created or old ones archived

Troubleshooting

  • Connection Issues: Verify HTTP credentials and Gerrit instance accessibility
  • Missing Projects: Check project names match exactly as shown in Gerrit
  • Permission Problems: Ensure auth provider configuration matches code host URL
  • User Access Issues: Verify users have connected their Gerrit accounts and permissions have synced