# Gerrit MCP Server Configuration (`gerrit_config.json`)

The `gerrit_mcp_server` is configured via a central JSON file located at
`gerrit_mcp_server/gerrit_config.json`. This file allows you to define
connection and authentication details for multiple Gerrit instances.

A sample file is provided at `gerrit_mcp_server/gerrit_config.sample.json` which
you can copy and customize.

## Interactive Setup (`/gerrit:setup`)

If your harness supports skills (tested with Claude Code), the `/gerrit:setup`
skill can create or repair `gerrit_config.json` for you interactively instead of
hand-editing the JSON. It prompts for each Gerrit host's URL and authentication
method, sets `default_gerrit_base_url`, and writes the file.

The skill is `disable-model-invocation`, so the model cannot run it on your
behalf — you must invoke `/gerrit:setup` yourself. It is written against the
[Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
open standard, so it is also expected to work in Gemini CLI, OpenAI Codex, and
other compatible harnesses, though only Claude Code has been verified.

The rest of this document describes the config file in full, which is useful
whether you write it by hand or want to understand what the skill produces.

## Top-Level Configuration

The configuration file has two main properties at its root:

| Key                       | Type   | Description                                                                                                                                                   |
| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default_gerrit_base_url` | string | The full URL of the Gerrit instance to use if a tool is called without a specific `gerrit_base_url` parameter.                                                |
| `gerrit_hosts`            | array  | A list of objects, where each object defines the connection and authentication details for a specific Gerrit instance. This is the core of the configuration. |
| `extensions`              | object | (Optional) Namespaced configuration blocks for extensions, keyed by extension name. See [Extensions](extensions.md#namespaced-configuration).                 |

______________________________________________________________________

## The `gerrit_hosts` Array

This is a list where you define each Gerrit instance you want to interact with.
The server will look through this list to find a host that matches the URL of a
given request.

Each host object has the following structure:

| Key              | Type   | Description                                                                                                                                          |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | string | A user-friendly name for the Gerrit instance (e.g., "Fuchsia", "Public Gerrit").                                                                     |
| `internal_url`   | string | (Optional) An alternative URL for the same host, often used for internal network access. The server will recognize both this and the `external_url`. |
| `external_url`   | string | The primary, publicly accessible URL for the Gerrit host.                                                                                            |
| `authentication` | object | A required object that specifies which authentication method to use for this host. See the detailed section below.                                   |

______________________________________________________________________

## Authentication Methods

The `authentication` object is the most important part of the configuration. It
tells the server how to authenticate its `curl` requests to the Gerrit API. You
must specify a `type` for each host. There are three supported types.

### 1. `git_cookies` (Recommended)

This method authenticates requests using the same `.gitcookies` file that Git
uses to authenticate command-line operations like `git push`. This is a
convenient option if you already have this set up.

To generate or update your credentials, log in to your Gerrit instance, navigate
to **Settings** (the gear icon), and find the **HTTP Credentials** section.
Gerrit will provide a script or commands to run that will configure your
`.gitcookies` file with the correct authentication token.

- **`type`**: `"git_cookies"`
- **`gitcookies_path`**: The path to your `.gitcookies` file (e.g.,
  `~/.gitcookies`).

**Example:**

```json
{
  "name": "GitCookies Auth Example",
  "external_url": "https://another-gerrit.com/",
  "authentication": {
    "type": "git_cookies",
    "gitcookies_path": "~/.gitcookies"
  }
}
```

If a matching cookie is not found in the file, the server will fall back to
making an unauthenticated request.

### 2. `gob_curl` (Google Internal)

This method is for developers working within Google's corporate network.
`gob-curl` is a tool that automatically handles authentication for internal
services.

- **`type`**: `"gob_curl"`

**Example:**

```json
{
  "name": "Fuchsia Open Source [Googlers]",
  "internal_url": "https://fuchsia-review.git.private.corporation.com/",
  "external_url": "https://fuchsia-review.googlesource.com/",
  "authentication": {
    "type": "gob_curl"
  }
}
```

### 3. `http_basic`

This is the standard and most common method for authenticating with a Gerrit
instance's REST API. It uses a generated HTTP password or token.

- **`type`**: `"http_basic"`

You can supply the credentials in one of two ways.

#### Preferred: credentials from a netrc file

If you omit both `username` and `auth_token`, the server lets `curl` read your
credentials from a netrc file (via `curl --netrc`), keyed by host. This is the
recommended setup — analogous to `git_cookies` — because it avoids duplicating
your token in `gerrit_config.json`.

Add an entry to your `~/.netrc` for the Gerrit host, e.g.:

```
machine fuchsia-review.googlesource.com login your-username password your-auth-token
```

- **`netrc_path`**: (Optional) Path to a non-default netrc file (e.g.
  `~/.netrc-gerrit`). Maps to `curl --netrc-file`. If omitted, curl uses your
  default `~/.netrc`.

**Example:**

```json
{
  "name": "Fuchsia Open Source",
  "external_url": "https://fuchsia-review.googlesource.com/",
  "authentication": {
    "type": "http_basic"
  }
}
```

#### Inline credentials

Alternatively, specify the credentials directly. If you set one of these, you
must set both.

- **`username`**: Your Gerrit username.
- **`auth_token`**: Your Gerrit HTTP password/token. You can usually generate
  this from your Gerrit user settings page under "HTTP Credentials - Obtain
  Password".

**Example:**

```json
{
  "name": "Fuchsia Open Source",
  "external_url": "https://fuchsia-review.googlesource.com/",
  "authentication": {
    "type": "http_basic",
    "username": "your-username",
    "auth_token": "your-auth-token"
  }
}
```

## Complete Configuration Example

Here is an example of a `gerrit_config.json` file that defines multiple hosts
using all available authentication methods.

```json
{
  "default_gerrit_base_url": "https://fuchsia-review.googlesource.com/",
  "gerrit_hosts": [
    {
      "name": "Fuchsia Open Source",
      "external_url": "https://fuchsia-review.googlesource.com/",
      "authentication": {
        "type": "http_basic",
        "username": "your-username",
        "auth_token": "your-auth-token"
      }
    },
    {
      "name": "Fuchsia Open Source [Googlers]",
      "internal_url": "https://fuchsia-review.git.private.corporation.com/",
      "external_url": "https://fuchsia-review.googlesource.com/",
      "authentication": {
        "type": "gob_curl"
      }
    },
    {
      "name": "AOSP (via gitcookies)",
      "external_url": "https://android-review.googlesource.com/",
      "authentication": {
        "type": "git_cookies",
        "gitcookies_path": "~/.gitcookies"
      }
    }
  ]
}
```