hermes-gerrit 0.0.1.dev26

Gerrit adapter for the Hermes agent gateway

hermes-gerrit

A Gerrit code-review platform adapter for the Hermes Agent 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.

Installation

PyPI (production):

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/:

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:

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

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. Every implementation patch in this repository traces back to a decision in that file.

License

GPL-3.0-or-later. See LICENSE.