Extract Gerrit config details into a reusable reference file The setup skill inlined the full configuration knowledge — the file location, all three authentication methods, and the config schema — which made it impossible for other skills to reuse without duplicating. Move that static reference into skills/setup/references/gerrit-config.md and trim SKILL.md to focus on the interactive setup flow, pointing at the reference for the details. This lets other skills consume the canonical config format from one place. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Change-Id: I38a85742bf420814c00d6831b0fca0ea6a6ac50a
diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md index 0a0670c..640a724 100644 --- a/skills/setup/SKILL.md +++ b/skills/setup/SKILL.md
@@ -32,7 +32,8 @@ ## Config file location The config file is `gerrit_mcp_server/gerrit_config.json` relative to the repo -root. Check whether it already exists before proceeding. +root (see `references/gerrit-config.md` for the override env var). Check whether +it already exists before proceeding. ## What to do @@ -45,68 +46,18 @@ 1. Ask for their primary Gerrit instance URL (or use `$ARGUMENTS` if a URL was provided). 2. Ask which authentication method they use for that host — present the three - options below. + options from `references/gerrit-config.md` (`git_cookies`, `gob_curl`, + `http_basic`). 3. Collect the additional fields required by the chosen method. 4. Ask if they have more Gerrit hosts to add; repeat steps 2–3 for each. 5. Set `default_gerrit_base_url` to the first host's URL. 6. Write the complete JSON to `gerrit_mcp_server/gerrit_config.json` and confirm success. -## Authentication methods +## Configuration details -**`git_cookies`** — recommended when you already push to Gerrit via `git` over -HTTP. Uses your `.gitcookies` file. Go to Gerrit → Settings → HTTP Credentials -to generate or refresh it. - -```json -{"type": "git_cookies", "gitcookies_path": "~/.gitcookies"} -``` - -**`gob_curl`** — Google internal only. `gob-curl` handles auth automatically; no -extra fields needed. - -```json -{"type": "gob_curl"} -``` - -**`http_basic`** — username and HTTP password token. Generate the token in -Gerrit → Settings → HTTP Credentials → "Obtain Password". - -The preferred form omits the credentials from the config and lets `curl` read -them from a netrc file (keyed by host), so they aren't duplicated in -`gerrit_config.json`. Add a line to `~/.netrc` like -`machine gerrit.example.com login YOUR_USERNAME password YOUR_HTTP_TOKEN`, then -configure: - -```json -{"type": "http_basic"} -``` - -Add an optional `"netrc_path"` to point at a non-default netrc file (maps to -`curl --netrc-file`). - -Alternatively, store the credentials inline (both fields required): - -```json -{"type": "http_basic", "username": "YOUR_USERNAME", "auth_token": "YOUR_HTTP_TOKEN"} -``` - -## Config schema - -```json -{ - "default_gerrit_base_url": "https://primary-gerrit.example.com/", - "gerrit_hosts": [ - { - "name": "Human-readable label", - "external_url": "https://gerrit.example.com/", - "internal_url": "https://gerrit.internal.example.com/", - "authentication": {} - } - ] -} -``` - -`internal_url` is optional. When present, the server recognises both URLs as the -same host, which is useful if you access the same instance via both an internal -and external address. +See [gerrit config reference](references/gerrit-config.md) for the full +configuration reference: authentication methods (with example JSON snippets for +each), the config schema, the file location and `GERRIT_CONFIG_PATH` override, +and the optional `internal_url` field. Consult it when collecting fields and +assembling the file.
diff --git a/skills/setup/references/gerrit-config.md b/skills/setup/references/gerrit-config.md new file mode 100644 index 0000000..1b77c7b --- /dev/null +++ b/skills/setup/references/gerrit-config.md
@@ -0,0 +1,79 @@ +# Gerrit MCP Server Configuration Reference + +Describes the `gerrit_config.json` file consumed by `gerrit_mcp_server`: where +it lives, the authentication methods it supports, and its full schema. Other +skills that read or write this config should rely on this reference rather than +duplicating the details. + +## Config file location + +The config file is `gerrit_mcp_server/gerrit_config.json` relative to the repo +root. + +The `GERRIT_CONFIG_PATH` environment variable can override this to point at a +custom config file. + +## Authentication methods + +**`git_cookies`** — recommended when you already push to Gerrit via `git` over +HTTP. Uses your `.gitcookies` file. Go to Gerrit → Settings → HTTP Credentials +to generate or refresh it. + +```json +{"type": "git_cookies", "gitcookies_path": "~/.gitcookies"} +``` + +**`gob_curl`** — Google internal only. `gob-curl` handles auth automatically; no +extra fields needed. + +```json +{"type": "gob_curl"} +``` + +**`http_basic`** — username and HTTP password token. Generate the token in +Gerrit → Settings → HTTP Credentials → "Obtain Password". + +The preferred form omits the credentials from the config and lets `curl` read +them from a netrc file (keyed by host), so they aren't duplicated in +`gerrit_config.json`. Add a line to `~/.netrc` like +`machine gerrit.example.com login YOUR_USERNAME password YOUR_HTTP_TOKEN`, then +configure: + +```json +{"type": "http_basic"} +``` + +Add an optional `"netrc_path"` to point at a non-default netrc file (maps to +`curl --netrc-file`). + +Alternatively, store the credentials inline (both fields required): + +```json +{"type": "http_basic", "username": "YOUR_USERNAME", "auth_token": "YOUR_HTTP_TOKEN"} +``` + +## Config schema + +```json +{ + "default_gerrit_base_url": "https://primary-gerrit.example.com/", + "gerrit_hosts": [ + { + "name": "Human-readable label", + "external_url": "https://gerrit.example.com/", + "internal_url": "https://gerrit.internal.example.com/", + "authentication": {} + } + ] +} +``` + +`internal_url` is optional. When present, the server recognises both URLs as the +same host, which is useful if you access the same instance via both an internal +and external address. + +`default_gerrit_base_url` should match one of the configured hosts' URLs; +conventionally it is set to the first host's URL. + +`authentication` must be one of the [methods](#authentication-methods) listed +above.