cenk1cenk2/hermes-bridge-gitlab repository overview

⁠hermes-bridge-gitlab

Bridges GitLab merge request and note webhooks that address the bot to Hermes runs, one thread per merge request or issue, and answers in the merge request or issue: an award, one status note edited in place and a reply in each discussion that asked. Talks directly to a Hermes⁠ API server — any deployment that exposes /v1/runs.

⁠Image

docker run --rm -p 8080:8080 cenk1cenk2/hermes-bridge-gitlab:latest

⁠Environment

Durations are milliseconds unless noted.

⁠Routes

⁠Events

Every event of the bot itself (GITLAB_BOT_ID) is dropped first, so nothing the bot writes starts a run. A delivery is handled once per Idempotency-Key (or webhook-id) header, and each input is sent once per note or merge request update.

Each merge request or issue is one thread, gitlab-<project>-mr-<iid> or gitlab-<project>-issue-<iid>, which is also the Hermes session. An input carries the instructions of its kind, GITLAB_WEBHOOK_INSTRUCTIONS_<KIND> or else GITLAB_WEBHOOK_INSTRUCTIONS_DEFAULT; kinds with different instructions are never steered into each other's runs, and its meta {projectId, noteableType, iid, discussionId, noteId, kind} says where to answer.

⁠Feedback

Every call to GitLab goes through one BullMQ queue with a global concurrency of 1 and a shared rate limit, so replicas never race each other on a merge request.

• A note that addresses the bot gets an eyes award at once, a stop note too.
• Asking the bot for a fix or a review on a closed or merged merge request starts no run; it leaves a notice note instead, This merge request is <state>, so no <kind> run was started, once per update.
• When a run is accepted, the thread opens one status note: a reply in the note's discussion for a mention, a new discussion for a review or a fix. The note is one sentence naming the ids to trace the thread by, <agent> has <state> the session through gitlab bridge, with key <key>, running in harness in session <session id> | run <run id>., where <agent> is AGENT_NAME, <key> is the thread key without its gitlab- prefix and <state> is accepted, turning failed or stopped when the run ends so. The answer, as Hermes streams it, follows that sentence and edits the note in place behind GITLAB_NOTE_DEBOUNCE, since edits notify nobody. A queued run, tool calls, todos and heartbeats stay off the note. A run a replica takes over is polled, so its note jumps from the partial answer to the final one.
• The run's answer is a reply in the discussion of each of its inputs, once per discussion, and in the status discussion for a review or a fix, Done. for a run without one; the status note keeps only its sentence. A failure, a denied command and a stop are replies too, ending in the same sentence with failed (a denied command too) or stopped, and leave the partial answer below the sentence of the status note; a stop is also answered in the discussion of the stop note, and a stop of a run whose input has no discussion opens the status note to reply in. A stop note with nothing running is answered Nothing is running..
• When the run ends, the bridge resolves the status discussion it started on a merge request, so it never blocks a merge; it never resolves a discussion an input came from, and issues have none to resolve. Review posts, Fixed in <sha>. replies, pushes and the resolution of review threads stay with the agent.
• On boot, every status note left open is handed back to the driver; one whose run cannot be resumed gets a restart reply and is closed, once across replicas and restarts.

⁠Logs

Every line carries a message that is a complete sentence fixed per event, its source class as context, and its ids, numbers and reasons as fields at the root of the JSON object ({"level":"log","message":"Created a run for the thread.","context":"DriverThreadService","run":"...","thread":"...","replayed":false}); text prints the same fields inline. Durations are durationMs; tokens and bodies are never logged.

• info: one line per HTTP request (method, path, status, duration, remote address; /healthz and /readyz only at debug), webhook verification or rejection with the Idempotency-Key and X-Gitlab-Event headers, each routed event and each dropped one with its reason (and, for a merge request that is not open, the kind it would have started and its state), queued notices, acknowledgement and thread input, skipped redeliveries, stops, opened status notes, posted replies, notices and awards, run creation, busy backoff, steers, follows and takeovers, finished runs with status and duration, Redis connections, the recovery sweep summary, the drain on shutdown and the runs and threads it hands over.
• debug: every run stream event, Hermes and GitLab call (method, path, status, duration), queued award, note and edit, status note edit, thread lock and run lease acquire, renew and release, and Redis transaction retry.
• warn and error: anything retried, dropped or failed, with its error.

⁠Fixtures

Run from apps/gitlab, tests/post-fixture.ts posts a fixture from tests/testdata to the webhook URL given as its second argument, with the webhook token, a fresh note id or updated_at and a fresh Idempotency-Key header. It runs on Node 26 as is, since Node strips the types:

GITLAB_WEBHOOK_TOKEN=... node tests/post-fixture.ts tests/testdata/note-merge-request.json https://bridge.example.com/v1/hooks/gitlab

⁠Development

The application lives in apps/gitlab of the workspace and runs on the shared core in packages/core; see the repository README.

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm --filter @kilic.dev/hermes-bridge-gitlab start