gitlab-openclaw-relay

Small relay for routing GitLab pipeline failure webhooks into OpenClaw sessions.

This project sits between GitLab and OpenClaw, filters noisy webhook traffic down to the failed pipeline events you actually care about, and wakes the right OpenClaw session or agent for triage.

Why this exists

GitLab can already emit webhooks for pipeline events, but raw webhook payloads are a lousy final destination.

What you usually want is:

• accept only failed pipeline events
• dedupe retries and duplicates
• route each repo to the right worker session
• wake OpenClaw with a compact, actionable summary
• let the agent decide whether humans need to be interrupted

That is what this relay does.

How it works

• exposes POST /gitlab/pipeline
• validates X-Gitlab-Token
• accepts only configured GitLab event types
• ignores non-failed pipelines
• dedupes repeated failed pipeline notifications in memory
• maps project.path_with_namespace to a configured OpenClaw session target
• shells out to openclaw cron add to wake a stable session with an agentTurn

Why a standalone relay

This could eventually become a native OpenClaw plugin. A standalone relay is the easier starting point:

• deploy and debug with curl independently of OpenClaw internals
• configure per repo without touching plugin packaging or reload cycles
• throw it away or replace it without breaking anything else

Requirements

• Node.js 20 or newer
• openclaw available on the PATH of the relay host
• an OpenClaw setup that accepts openclaw cron add ...
• GitLab project or group webhook access

Install

git clone <repo-url>
cd gitlab-openclaw-relay
cp config.example.json config.json
pnpm install
pnpm start

Local config hygiene

Do not commit config.json.

This repo is meant to keep only config.example.json under version control. Your real webhook secret, routing targets, and local relay settings should live in the ignored config.json file.

Configuration

Edit config.json.

Example:

{
  "listen": {
    "host": "127.0.0.1",
    "port": 4318
  },
  "gitlab": {
    "secret": "replace-me",
    "acceptEvents": ["Pipeline Hook"],
    "dedupeWindowMs": 900000
  },
  "openclaw": {
    "binary": "openclaw"
  },
  "routes": [
    {
      "project": "group/project-one",
      "sessionTarget": "session:project-one-build-failures",
      "agentId": "default-agent"
    },
    {
      "project": "group/project-two",
      "sessionTarget": "session:project-two-build-failures",
      "agentId": "ops-agent"
    }
  ],
  "fallback": {
    "sessionTarget": "session:build-failures",
    "agentId": "default-agent"
  }
}

Config fields

listen

• host: bind address
• port: bind port

gitlab

• secret: webhook secret token expected from X-Gitlab-Token
• acceptEvents: allowed GitLab event names, usually Pipeline Hook
• dedupeWindowMs: in-memory duplicate suppression window

openclaw

• binary: optional path to the openclaw binary

routes

List of exact project-path matches.

Each route supports:

• project: GitLab path_with_namespace
• sessionTarget: OpenClaw target session key like session:my-repo-builds
• agentId: optional agent to wake, defaults to default-agent
• channel: optional announce channel passed through to openclaw cron add
• accountId: optional announce account id passed through to openclaw cron add

fallback

Used when no explicit route matches.

GitLab webhook setup

In GitLab project or group settings:

• URL: https://your-host/gitlab/pipeline
• Secret token: same value as gitlab.secret
• Trigger: Pipeline events

Health check

GET /healthz

Returns:

{ "ok": true }

macOS launchd setup

If you are running this on macOS, use launchd instead of a loose terminal process.

Included files:

• bin/run-relay.sh — wrapper that discovers the repo root, sets RELAY_CONFIG, and writes logs to .run/
• deploy/launchd/com.example.gitlab-openclaw-relay.plist — example LaunchAgent plist; replace placeholder paths before loading it

Example setup:

cd gitlab-openclaw-relay
cp config.example.json config.json
pnpm install
chmod +x bin/run-relay.sh
cp deploy/launchd/com.example.gitlab-openclaw-relay.plist ~/Library/LaunchAgents/
# Edit the copied plist and replace /ABSOLUTE/PATH/TO/... with your real checkout path.
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.example.gitlab-openclaw-relay.plist 2>/dev/null || true
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.gitlab-openclaw-relay.plist
launchctl kickstart -k gui/$(id -u)/com.example.gitlab-openclaw-relay

Useful checks:

launchctl print gui/$(id -u)/com.example.gitlab-openclaw-relay
curl http://127.0.0.1:4318/healthz

Logs land in .run/, which is intentionally ignored by git.

What OpenClaw receives

For each accepted failure, the relay creates a one-shot cron job like this:

openclaw cron add \
  --name gitlab-failure-... \
  --at 10s \
  --delete-after-run \
  --session session:project-one-build-failures \
  --message "GitLab pipeline failure..." \
  --agent default-agent \
  --announce

That wakes a stable OpenClaw session with enough context to inspect the failure and continue triage.

Caveats

Current limitations:

• dedupe is in-memory only
• pipeline failures only, not standalone job webhooks
• exact project matching only
• delivery currently shells out to the OpenClaw CLI instead of using direct gateway RPC

Roadmap ideas

• persistent dedupe store
• job webhook support
• branch-specific routing
• glob or regex project matching
• direct gateway RPC delivery
• optional native OpenClaw plugin version
• optional fetch of failed job logs before wakeup

License

MIT