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.

⁠Slack

With SLACK_ENABLED, a run that completes with an answer posts one card to SLACK_CHANNEL: the title <agent> answered <project>!<iid> <title> on GitLab (# for an issue), a green bar, the answer quoted with its paragraph breaks kept and cut at whole lines to SLACK_ANSWER_LIMIT with a +more marker after a blank line when it is longer, link buttons to the thread the answer was posted in, when a note started the run, and to the merge request or issue, and the time it was posted. A run that fails, is stopped, has a command denied or completes without output posts nothing, and each run is posted once across replicas. A Slack failure is logged and never touches the GitLab replies. The buttons are plain links, so the Slack app needs no interactivity request URL.

Answer cards are post-only: no reaction polling, user lookups or manual-resolution edits run at startup or afterward. The bot needs only chat:write and channel membership for these posts. Posting claims remain in Redis under QUEUE_PREFIX for SLACK_TTL; replay after that claim expires can post again. This is not transactional exactly-once delivery across Slack and Redis.

Historical MANUALLY RESOLVED messages are not edited or deleted. Old card records, reaction indexes and resolution locks can remain inert in Redis; no data cleanup is required. Board reporting, its independent reporting controls and the run lifecycle are unchanged.

⁠Board

Reports include optional reporting: { board: boolean, post: boolean }: the receiver filters board visibility and agent announcement posts independently. Missing reporting or either missing flag means true. Both-disabled reports are still retained and delivered so the receiver can clear stale visibility; flags never suppress execution, results, errors or SSE. The resolved policy survives activity, terminal events, retries, outbox delivery and hourly reconciliation without renewing source expiry. Direct GitLab webhook threads default to { board: true, post: true }. This policy does not disable platform replies or the separate Slack answer cards.

With BOARD_ENABLED, every thread posts its state to BOARD_URL as JSON {"key","platform","sessionId","state","title","link","links","error","runId","at","sourceActivityAt","reporting"}, next to the GitLab replies. running means WORKING while a turn is queued or executing; done means IDLE immediately after completion, awaiting another message. Failures, stops and denied commands remain distinct as failed, stopped and approval_denied. Real tool, message, todo and thought activity refreshes running at most once per BOARD_REFRESH_INTERVAL across replicas; silence never changes an active turn to idle, and synthetic idle sweeps send no board updates. Working and completed entries expire from their last known source activity, not their last delivery; the next real turn reports working again. sessionId is optional and comes from the thread's Hermes session, key is the thread key, and title and link identify the merge request or issue. Optional links carries additional source links as [{"text","url"}] from input metadata when present; existing merge request/issue titles and primary links remain unchanged. Board state retains source metadata for activity updates without inputs, including updates from another replica. error carries the failure or denied command. at is an epoch-millisecond version that increases when a new projection is persisted; it orders updates, not receipt time. Optional sourceActivityAt is epoch milliseconds of the last known real accepted, queued, tool, message, thought, todo or terminal lifecycle activity. Even activity coalesced within BOARD_REFRESH_INTERVAL persists a new immutable projection with its source time. Silence, replay and unchanged status checks do not create activity or a fresh version. A repaired source change uses its known activity time, not query time. Settled and superseded occurrences reject late callbacks.

The complete latest projection and its pending delivery are stored atomically with a retained index, including terminal threads after driver cleanup. Driver lifecycle transitions await only Redis persistence; board delivery and platform/Slack HTTP remain detached. Immediate delivery keeps the BOARD_RETRIES budget. After releasing delivery ownership, the sender checks for a newer due pending version and drains it immediately, including reports persisted by another replica while delivery was finishing. The exhausted version itself waits for startup or hourly reconciliation rather than retrying in a tight loop. An acknowledgement clears only its exact version, so it cannot discard a newer report. Reconciliation also replays acknowledged latest projections to restore lost receiver history, byte-for-byte with the same at, source time, session, links, error and reporting policy. Redis token-owned locks coordinate replicas; at-least-once delivery can repeat an identical payload.

Receiver integration must deduplicate equal/older at without another announcement and expire entries at sourceActivityAt + HERMES_TTL, using only the remaining delay and ignoring expired replays. Receipt time is transport diagnostics, never source activity. Deploy that receiver support before enabling repeated replay; legacy JSON fields and the endpoint remain unchanged. Receiver rendering remains event-driven at 60 seconds, and daily message rotation belongs to the receiver, not this sender.

Active-run repair uses the established HERMES_URL and HERMES_API_KEY through GET /v1/runs/{id}; it never sends driver input, recovers a driver thread, or emits platform activities. The driver record and board version must still match the snapshot taken before the query. Explicit stop and denied-stop state override raw run status, while an interrupted run eligible for driver resubmission stays running. Hermes updated_at is seconds of a status write, not user activity: only a recognized activity/terminal event can supply a recovery source time, and interruption queries never use it because GET can synthesize it. Otherwise repair preserves a known board source time or the original follower start time; unknown or expired provenance is skipped. Terminal history with neither a retained projection nor a surviving driver source cannot be reconstructed, and no timestamps are invented for it. Existing refresh, retry and TTL setting names remain unchanged.

⁠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

⁠Automatic reviews

The existing token-guarded POST /v1/hooks/gitlab handles automatic chart and plan reviews as well as explicit requests. Pulumi owns project eligibility and sets X-Gitlab-Review-Kind: chart, pulumi or terraform on eligible labrat-events hooks. The token authenticates that provisioned metadata before any lookup or driver call. Unmarked projects do not start automatic reviews; JSON fields cannot select a job or override instructions. Keep the shared webhook token and hook configuration restricted to trusted administrators.

The bridge, not the gateway or runs broker, owns classification, skill selection, label exclusion and GitLab reporting. Chart reviews require open Renovate MR open/reopen/update hooks. Plan reviews require an open Renovate MR and a successful plan (Pulumi) or tf-plan (Terraform) build in an MR pipeline hook. Drafts and skip-CI titles are ignored. The same classifier preserves notes, assignments, review requests and lifecycle events. An explicit MR request takes precedence over automatic dispatch for that event.

The exact, case-sensitive automerge label excludes automatic reviews. Chart hooks use their top-level and MR attribute label objects without a GitLab lookup. Pipeline MR objects omit labels, so eligible pipeline deliveries read current labels through the existing client. The same read rejects closed, draft, skip-CI and stale-head targets. Flags and descriptions do not exclude reviews. Failed or incomplete required lookups answer 503 without driver or reporting side effects; accepted and ignored events answer 200 ok. A chart hook without either label list also fails closed. Delivered chart labels can be stale; this does not cancel work already accepted or predict labels added afterward.

The job, project, MR and full commit digest form the input identity (chart identity also includes source branch and title). The driver's atomic seen-key and inbox transaction deduplicates concurrent deliveries across replicas without a claim-before-enqueue crash gap. Retries after a failed lookup or enqueue remain eligible. Each automatic identity has its own gitlab-<project>-mr-<iid>-review-<digest> thread with batching and steering off. Existing GitLab discussion sinks own status notes, replies and completion reporting. Explicit note mentions, reviewer requests and assignments keep their behavior regardless of automatic exclusions.

GITLAB_WEBHOOK_BODY_LIMIT defaults to 4194304 bytes for large webhook descriptions. Generic runs remain platform-neutral and receive no GitLab credentials or admission logic.

Automatic and explicit events share this single endpoint. There is no per-job review controller or gateway automatic route. Keep direct Kargo/IaC job endpoints and generic runs independent. Deploy shared-endpoint support and consolidate Pulumi subscriptions before deploying removal of old automatic paths. Do not replay historical deliveries outside the driver deduplication retention window.