openclaw-channel-github 0.1.0

package/docs/usage.md

@@ -0,0 +1,393 @@
+# OpenClaw GitHub Channel - Usage Guide
+
+## Overview
+
+The OpenClaw GitHub Channel is a webhook-based integration that connects GitHub repositories to the OpenClaw AI agent framework. It enables AI-powered assistance directly within GitHub Issues, Pull Requests, Discussions, and CI/CD workflows.
+
+**Key capabilities:**
+- Listen to GitHub webhook events (issues, PRs, reviews, discussions, CI)
+- Normalize events into a unified format for the OpenClaw Gateway
+- Trigger agent responses based on @mentions, slash commands, labels, or auto-trigger rules
+- Send responses back as GitHub comments or PR reviews
+- Prevent bot loops via sender filtering and outbound markers
+- Support multi-account / multi-installation setups
+
+## Quick Start
+
+### Prerequisites
+
+1. A GitHub App with the following permissions:
+   - **Issues**: Read & Write
+   - **Pull Requests**: Read & Write
+   - **Discussions**: Read & Write (optional)
+   - **Metadata**: Read
+   - **Contents**: Read (optional, for file context)
+
+2. Webhook events configured on the GitHub App:
+   - `issues`
+   - `issue_comment`
+   - `pull_request`
+   - `pull_request_review`
+   - `pull_request_review_comment`
+   - `discussion` (optional)
+   - `discussion_comment` (optional)
+   - `check_run` (optional)
+   - `workflow_run` (optional)
+
+3. Go 1.21+ installed
+
+### Installation
+
+#### Option 1: OpenClaw Plugin Install (Recommended)
+
+```bash
+# Install directly via the OpenClaw CLI plugin system
+openclaw plugins install github.com/Iceber/openclaw-channel-github
+
+# Verify the installation
+openclaw plugins list
+
+# View channel status
+openclaw channels list
+openclaw channels status --channel github
+openclaw channels capabilities --channel github
+```
+
+#### Option 2: Build from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/Iceber/openclaw-channel-github.git
+cd openclaw-channel-github
+
+# Build the binary
+make build
+
+# Or build manually with Go
+go build -o openclaw-github-channel ./cmd/openclaw-github-channel/
+
+# Install system-wide (optional)
+make install
+
+# Run with a config file
+./openclaw-github-channel -config config.json
+```
+
+#### Option 3: Go Install
+
+```bash
+go install github.com/Iceber/openclaw-channel-github/cmd/openclaw-github-channel@latest
+```
+
+### Minimal Configuration
+
+Create a `config.json` file:
+
+```json
+{
+  "server": {
+    "addr": ":8080"
+  },
+  "channel": {
+    "enabled": true,
+    "mode": "app",
+    "appId": 123456,
+    "installationId": 78901234,
+    "privateKeyPath": "/path/to/github-app-private-key.pem",
+    "webhookSecret": "your-webhook-secret",
+    "repositories": ["your-org/your-repo"],
+    "trigger": {
+      "requireMention": true,
+      "botUsername": "your-bot-name",
+      "commands": ["/openclaw"],
+      "labels": ["ai-review", "ai-help"]
+    },
+    "ignoreBots": true
+  }
+}
+```
+
+## Configuration Reference
+
+### Server Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `server.addr` | string | `:8080` | HTTP server listen address |
+
+### Channel Configuration
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `channel.enabled` | bool | Yes | Enable/disable the channel |
+| `channel.mode` | string | Yes | Authentication mode: `"app"` or `"token"` |
+| `channel.appId` | int | Yes (app mode) | GitHub App ID |
+| `channel.installationId` | int | Yes (app mode) | GitHub App Installation ID |
+| `channel.privateKeyPath` | string | Yes (app mode) | Path to GitHub App private key PEM file |
+| `channel.webhookSecret` | string | Yes | Webhook signing secret |
+| `channel.repositories` | []string | Yes | Allowlisted repositories (`"owner/repo"` format) |
+| `channel.ignoreBots` | bool | No | Ignore events from bot accounts |
+
+### Trigger Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `channel.trigger.requireMention` | bool | `false` | Require `@bot` mention to trigger |
+| `channel.trigger.botUsername` | string | - | Bot username for mention detection |
+| `channel.trigger.commands` | []string | - | Slash command prefixes (e.g., `["/openclaw"]`) |
+| `channel.trigger.labels` | []string | - | Labels that trigger the bot when applied |
+
+### Auto-Trigger Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `channel.autoTrigger.onPROpened` | bool | `false` | Auto-trigger when a PR is opened |
+| `channel.autoTrigger.onIssueOpened` | bool | `false` | Auto-trigger when an issue is opened |
+
+### Outbound Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `channel.outbound.mode` | string | `"comment"` | Response mode: `"comment"`, `"review"`, or `"auto"` |
+| `channel.outbound.outboundMarker` | string | `<!-- openclaw-outbound -->` | Hidden HTML comment for bot loop prevention |
+
+### Rate Limiting
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `channel.rateLimit.maxEventsPerMinute` | int | 0 (unlimited) | Maximum events to process per minute |
+
+### Multi-Account Configuration
+
+For managing multiple GitHub App installations:
+
+```json
+{
+  "channel": {
+    "enabled": true,
+    "accounts": {
+      "default": {
+        "mode": "app",
+        "appId": 123456,
+        "installationId": 111,
+        "privateKeyPath": "/keys/default.pem",
+        "webhookSecret": "secret-1",
+        "repositories": ["org-a/repo-1", "org-a/repo-2"]
+      },
+      "enterprise": {
+        "mode": "app",
+        "appId": 654321,
+        "installationId": 222,
+        "privateKeyPath": "/keys/enterprise.pem",
+        "webhookSecret": "secret-2",
+        "repositories": ["org-b/repo-x"]
+      }
+    },
+    "trigger": {
+      "requireMention": true,
+      "botUsername": "openclaw-bot"
+    }
+  }
+}
+```
+
+## Trigger Model
+
+The channel supports four trigger modes:
+
+### 1. @Mention Trigger
+The bot responds when mentioned in a comment:
+```
+@openclaw-bot Please summarize this issue.
+```
+
+### 2. Command Trigger
+The bot responds to slash commands:
+```
+/openclaw review
+/openclaw summarize
+```
+
+### 3. Label Trigger
+The bot responds when a configured label is applied to an issue or PR:
+- Apply label `ai-review` → triggers analysis
+- Apply label `ai-help` → triggers assistance
+
+### 4. Auto Trigger
+The bot automatically responds to certain events:
+- PR opened → auto-analyze (when `autoTrigger.onPROpened` is true)
+- Issue opened → auto-respond (when `autoTrigger.onIssueOpened` is true)
+
+### Trigger Priority
+1. @Mention (highest priority)
+2. Slash command
+3. Label match
+4. Auto-trigger (lowest priority)
+
+## Supported Events
+
+### Core Events (Phase 1)
+| GitHub Event | Action | Normalized Type |
+|-------------|--------|-----------------|
+| `issue_comment` | `created` | `comment` |
+| `issues` | `opened` | `issue_body` |
+| `pull_request` | `opened` | `pr_body` |
+| `pull_request_review` | `submitted` | `review` |
+| `pull_request_review_comment` | `created` | `review_comment` |
+
+### Context Events (Phase 3)
+| GitHub Event | Action | Normalized Type |
+|-------------|--------|-----------------|
+| `issues` | `edited` | `context_update` |
+| `issues` | `closed` | `context_update` |
+| `issues` | `reopened` | `context_update` |
+| `issues` | `labeled` | `context_update` |
+| `issue_comment` | `edited` | `context_update` |
+| `pull_request` | `edited` | `context_update` |
+| `pull_request` | `closed` | `context_update` |
+| `pull_request` | `synchronize` | `context_update` |
+| `pull_request` | `labeled` | `context_update` |
+
+### Discussion Events (Phase 4)
+| GitHub Event | Action | Normalized Type |
+|-------------|--------|-----------------|
+| `discussion` | `created` | `discussion_body` |
+| `discussion_comment` | `created` | `comment` |
+
+### CI Events (Phase 4)
+| GitHub Event | Action | Normalized Type |
+|-------------|--------|-----------------|
+| `check_run` | `completed` | `ci_status` |
+| `workflow_run` | `completed` | `ci_status` |
+
+## Session Model
+
+Each GitHub thread (Issue, PR, Discussion) maps to a stable session:
+
+```
+github:<owner>/<repo>:issue:<number>
+github:<owner>/<repo>:pull_request:<number>
+github:<owner>/<repo>:discussion:<number>
+```
+
+For PR review threads (fine-grained):
+```
+github:<owner>/<repo>:pull_request:<number>:review-thread:<threadId>
+```
+
+Multiple comments within the same thread always map to the same session, enabling continuous conversation context.
+
+## Bot Loop Prevention
+
+Three layers of protection:
+
+1. **Sender type filtering**: Events from `Bot` type accounts are ignored (when `ignoreBots` is true)
+2. **Username matching**: Events from the bot's own username are always ignored
+3. **Outbound marker**: Responses include a hidden HTML marker (`<!-- openclaw-outbound -->`) that is detected in incoming events to prevent self-triggering
+
+## Security
+
+### Webhook Signature Verification
+All webhook payloads are verified using HMAC-SHA256 (`X-Hub-Signature-256` header).
+
+### Repository Allowlist
+Only events from explicitly allowlisted repositories are processed.
+
+### Delivery Deduplication
+GitHub may retry webhook deliveries. The channel uses delivery ID tracking to prevent duplicate processing.
+
+### Minimal Permissions
+Only request the minimum GitHub App permissions needed:
+- Issues: Read/Write
+- Pull Requests: Read/Write
+- Metadata: Read
+
+## Running Tests
+
+```bash
+# Run all unit tests
+go test ./...
+
+# Run with race detector
+go test -race ./...
+
+# Run e2e tests only
+go test ./e2e/...
+
+# Run with verbose output
+go test -v ./...
+```
+
+## Architecture
+
+```
+GitHub Webhook POST /webhook
+  → HMAC-SHA256 signature verification
+  → Delivery ID deduplication
+  → Event type parsing
+  → Normalization to NormalizedEvent (with context metadata)
+  → Repository allowlist check
+  → Bot loop prevention (sender type + username + outbound marker)
+  → Trigger evaluation (@mention / /command / label / auto)
+  → MessageHandler callback
+  → Outbound response (comment or PR review)
+```
+
+### Package Structure
+
+```
+cmd/openclaw-github-channel/   # Entry point
+pkg/
+  config/                       # Configuration loading and validation
+  auth/                         # GitHub App authentication, webhook verification
+  events/                       # Webhook event types and parsing
+  normalizer/                   # Event normalization to unified format
+  routing/                      # Session keys, trigger matching
+  outbound/                     # GitHub API client (comments, reviews, reactions)
+  state/                        # Idempotency and deduplication
+  server/                       # HTTP webhook handler
+e2e/                            # End-to-end tests
+docs/                           # Documentation
+```
+
+## OpenClaw Plugin Integration
+
+This channel is packaged as an OpenClaw plugin and can be managed via the `openclaw` CLI.
+
+### Plugin Manifest
+
+The `plugin.yaml` in the repository root defines the plugin metadata, capabilities, and configuration schema. It is used by the `openclaw plugins install` command to register and configure the channel.
+
+### CLI Commands
+
+```bash
+# Install the plugin
+openclaw plugins install github.com/Iceber/openclaw-channel-github
+
+# List installed plugins
+openclaw plugins list
+
+# Remove the plugin
+openclaw plugins remove github
+
+# Channel management
+openclaw channels add --channel github
+openclaw channels list
+openclaw channels status --channel github
+openclaw channels capabilities --channel github
+openclaw channels logs --channel github
+```
+
+### Capabilities
+
+| Capability | Supported |
+|-----------|-----------|
+| Text inbound | ✅ |
+| Text outbound | ✅ |
+| Reaction | ✅ |
+| Edit awareness | ✅ |
+| Delete awareness | ❌ |
+| Attachment send | ❌ |
+| Thread reply | ✅ |
+| Rich review output | ✅ |
+| Realtime typing / presence | ❌ |

package/openclaw.plugin.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://docs.openclaw.ai/schemas/plugin.json",
+  "name": "openclaw-channel-github",
+  "version": "0.1.0",
+  "description": "GitHub Channel for OpenClaw — connects GitHub Issues, Pull Requests, Discussions, and CI/CD workflows to the OpenClaw AI agent framework via webhooks.",
+  "author": "Iceber",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Iceber/openclaw-channel-github",
+  "repository": "https://github.com/Iceber/openclaw-channel-github",
+  "keywords": ["github", "channel", "webhook", "issues", "pull-requests", "code-review"],
+  "main": "dist/index.js",
+  "channels": [
+    {
+      "id": "github",
+      "name": "GitHub",
+      "description": "GitHub Issues, Pull Requests, Discussions, and CI/CD webhook integration",
+      "capabilities": {
+        "textInbound": true,
+        "textOutbound": true,
+        "reaction": true,
+        "editAwareness": true,
+        "deleteAwareness": false,
+        "attachmentSend": false,
+        "threadReply": true,
+        "richReviewOutput": true,
+        "realtimeTyping": false,
+        "realtimePresence": false
+      },
+      "events": [
+        "issues",
+        "issue_comment",
+        "pull_request",
+        "pull_request_review",
+        "pull_request_review_comment",
+        "discussion",
+        "discussion_comment",
+        "check_run",
+        "workflow_run"
+      ],
+      "webhook": {
+        "path": "/webhook",
+        "method": "POST"
+      },
+      "healthCheck": {
+        "path": "/health",
+        "interval": "30s"
+      }
+    }
+  ],
+  "permissions": {
+    "issues": "write",
+    "pull_requests": "write",
+    "metadata": "read",
+    "discussions": "write",
+    "contents": "read"
+  },
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "server": {
+        "type": "object",
+        "properties": {
+          "addr": { "type": "string", "default": ":8080" }
+        }
+      },
+      "channel": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "mode": { "type": "string", "enum": ["app", "token"], "default": "app" },
+          "appId": { "type": "number" },
+          "installationId": { "type": "number" },
+          "privateKeyPath": { "type": "string" },
+          "webhookSecret": { "type": "string" },
+          "repositories": { "type": "array", "items": { "type": "string" } },
+          "ignoreBots": { "type": "boolean", "default": true },
+          "trigger": {
+            "type": "object",
+            "properties": {
+              "requireMention": { "type": "boolean", "default": true },
+              "botUsername": { "type": "string" },
+              "commands": { "type": "array", "items": { "type": "string" } },
+              "labels": { "type": "array", "items": { "type": "string" } }
+            }
+          },
+          "outbound": {
+            "type": "object",
+            "properties": {
+              "mode": { "type": "string", "enum": ["comment", "review", "auto"], "default": "comment" },
+              "outboundMarker": { "type": "string", "default": "<!-- openclaw-outbound -->" }
+            }
+          },
+          "autoTrigger": {
+            "type": "object",
+            "properties": {
+              "onPROpened": { "type": "boolean", "default": false },
+              "onIssueOpened": { "type": "boolean", "default": false }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "openclaw-channel-github",
+  "version": "0.1.0",
+  "description": "GitHub Channel for OpenClaw — connects GitHub Issues, Pull Requests, Discussions, and CI/CD workflows to the OpenClaw AI agent framework via webhooks.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "config.example.json",
+    "docs",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/main.js",
+    "dev": "ts-node src/main.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run e2e/",
+    "lint": "eslint src/ e2e/",
+    "clean": "rm -rf dist",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "openclaw",
+    "github",
+    "channel",
+    "webhook",
+    "issues",
+    "pull-requests",
+    "code-review"
+  ],
+  "author": "Iceber",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Iceber/openclaw-channel-github.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "github",
+      "label": "GitHub",
+      "selectionLabel": "GitHub (Issues and PRs)",
+      "docsPath": "/channels/github",
+      "docsLabel": "github",
+      "blurb": "GitHub Issues, Pull Requests, Discussions, and CI/CD webhook integration.",
+      "aliases": [
+        "gh"
+      ]
+    },
+    "install": {
+      "npmSpec": "openclaw-channel-github",
+      "localPath": ".",
+      "defaultChoice": "local"
+    }
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0",
+    "ts-node": "^10.9.0"
+  }
+}