Metadata-Version: 2.4
Name: hermes-gerrit
Version: 0.0.1.dev26
Summary: Gerrit adapter for the Hermes agent gateway
Author: Monty Taylor
Author-email: mordred@inaugust.com
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asyncssh<3,>=2.18
Requires-Dist: httpx<1,>=0.28
Dynamic: author-email
Dynamic: license-file
Dynamic: requires-dist

# hermes-gerrit

A Gerrit code-review platform adapter for the [Hermes
Agent](https://hermes-agent.nousresearch.com/) gateway. It connects to
a Gerrit SSH endpoint, streams `gerrit stream-events`, and exposes
five review tools (`fetch_diff`, `fetch_file`, `fetch_change`,
`inline_comment`, `review`). Stream + writes go over SSH; reads use
Gerrit's public REST API. Mirrors the contract of the existing
OpenClaw Gerrit channel plugin so prompts and docs read the same
regardless of which adapter the agent is running on.

## Status

Pre-1.0. Spec-locked 2026-05-05. Implementation in progress; see the
patch series plan in
[`doc/source/developer/specs/hermes-gerrit-adapter.rst`](doc/source/developer/specs/hermes-gerrit-adapter.rst).

## Installation

**PyPI (production):**

```bash
pip install hermes-gerrit
```

That's it. Hermes discovers the plugin via the `hermes_agent.plugins`
entry-point group — no `plugin.yaml` required.

**Dev / clone path:**

Symlink (or check out) this repo into `~/.hermes/plugins/gerrit/`:

```bash
git clone https://opendev.org/inaugust/hermes-gerrit ~/.hermes/plugins/gerrit
```

The `plugin.yaml` at the repo root is what the dev/clone path uses to
discover the plugin.

`hermes-agent` itself must be installed separately — it is *not* a
runtime dependency of this package.

## Required environment

| Variable        | Purpose                                          |
|-----------------|--------------------------------------------------|
| `GERRIT_SERVER` | Gerrit SSH host (e.g. `review.opendev.org`)      |
| `GERRIT_USER`   | SSH username                                     |
| `GERRIT_SSHKEY` | Path to the private SSH key to authenticate with |

Read tools (`fetch_diff`, `fetch_file`, `fetch_change`) hit Gerrit's
public REST API at `https://${GERRIT_SERVER}/...` with no
authentication; only the SSH key is required, and only for
`stream-events` and writes (`inline_comment`, `review`).

## Required Gerrit account permissions

The Gerrit account whose SSH key you give the adapter must have:

- **SSH access** (the `Stream Events` capability is server-wide; ask
  your Gerrit admin if `gerrit stream-events` rejects you).
- **`label-Code-Review` permission** in the relevant project's
  `refs/heads/*` ACL, with a range that includes `-1..+1`. The adapter
  hard-clamps Code-Review votes to ±1 — never +2/-2.
- **No** `label-Verified` or `label-Workflow` permissions are needed —
  those labels are hard-zeroed in code (only Zuul votes Verified, only
  humans set Workflow).

## Configuration

Multi-account, mirrored from the TS plugin's
`channels.gerrit.accounts.<id>` shape. In hermes' platform config:

```yaml
gateway:
  platforms:
    gerrit:
      enabled: true
      extra:
        accounts:
          opendev:
            host: review.opendev.org
            port: 29418
            username: my-bot
            sshKeyPath: ~/.ssh/id_ed25519
            allowFrom:
              - alice
              - bob
            projects:
              - openstack/nova
              - openstack/keystone
            mentionNames:
              - my-bot
            enabled: true
```

The `projects` allowlist is mandatory — see the safety section of the
spec for why an empty/missing allowlist must fail validation rather
than silently watch nothing.

## Tests

```bash
pip install -e .
pip install -r test-requirements.txt
pytest -q
```

## Documentation

Build the docs locally with:

```
nox -s docs
```

Output lands in `doc/build/html/`.

## Spec

The authoritative design doc is
[`doc/source/developer/specs/hermes-gerrit-adapter.rst`](doc/source/developer/specs/hermes-gerrit-adapter.rst).
Every implementation patch in this repository traces back to a
decision in that file.

## License

GPL-3.0-or-later. See [LICENSE](LICENSE).
