Gerrit

A Gerrit instance can be connected to Sourcegraph as follows:

• Gerrit
  • Configure Gerrit as a code host connection
  • Add Gerrit as an authentication provider
  • Have users authenticate their Sourcegraph accounts using their Gerrit HTTP credentials
  • Configuration
    • admin/external_service/gerrit.schema.json

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.
2. On the following screen, select Gerrit as the code host of choice.
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": "<admin username>",
  "password": "<admin 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
}

4. The provided username and password must be the HTTP credentials of an admin account on Gerrit. See the Gerrit HTTP documentation for details on how to generate HTTP credentials.
   The Gerrit instance has to have HTTPS clones enabled (the default). download.scheme=http. Sourcegraph cannot clone Gerrit repos via SSH.
5. 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:

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

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".
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
}

4. 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.
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
}