diff --git a/.env.example b/.env.example index bf7311b..097abbf 100644 --- a/.env.example +++ b/.env.example @@ -5,6 +5,9 @@ GITHUB_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" GITHUB_CLIENT_ID=your-client-id GITHUB_CLIENT_SECRET=your-client-secret +# Gitea (optional — to receive Gitea webhooks) +GITEA_WEBHOOK_SECRET=your-gitea-webhook-secret + # Discord DISCORD_TOKEN=your-bot-token DISCORD_PUBLIC_KEY=your-public-key diff --git a/AGENTS.md b/AGENTS.md index 849d59d..c5442dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,8 @@ Core pipeline: GitHub Webhook → Worker (verify + filter + format) → Discord - HTTP framework: Hono - Discord interactions: HTTPS Interactions Endpoint (`POST /discord/interactions`, Ed25519-signed) — no Discord Gateway / Durable Object; bot stays offline, messages always sent via REST - Storage: Cloudflare KV (tokens, OAuth state, route config `config:routes`, group config `config:groups`, admin sessions, delivery dedup, message-update tracking `msg:*`, i18n overrides `i18n:*`) + D1 (`send_logs`, `discord_links`, `telegram_links`) -- Signature verification: Web Crypto API (HMAC-SHA256 for GitHub, Ed25519 for Discord, timing-safe secret-token compare for Telegram) +- Signature verification: Web Crypto API (HMAC-SHA256 for GitHub/Gitea, Ed25519 for Discord, timing-safe secret-token compare for Telegram) +- Webhook providers: pluggable forge adapters under `src/providers/` (github, gitea) — each verifies its own signature format and normalizes its payload to a GitHub-shaped `WebhookEvent`; GitLab etc. can be added later - GitHub OAuth: octokit (token is stored hashed for reverse lookup) - Admin WebUI: `/admin` config console, OAuth-session protected via `ADMIN_USER_IDS` whitelist - Local dev: wrangler + Miniflare @@ -27,10 +28,18 @@ src/ ├── server.ts # Hono app: /health, /webhook, /discord/interactions, /telegram/webhook, mounts /auth, /admin + / ├── core/ │ └── dispatch.ts # Platform-neutral dispatch: match routes → formatEvent → driver.send/edit (recordSend + group filter) -├── events/ # GitHub webhook pipeline: verify signature, parse event, match route -│ ├── verify.ts # HMAC signature verify (Web Crypto, timing-safe) -│ ├── parse.ts # parseEvent (headers + body → WebhookEvent) +├── events/ # Provider-agnostic route matching │ └── match.ts # matchRoute, eventOwners, extractBranch, keyword regex filtering +├── providers/ # Forge webhook providers (verify + parse/normalize to GitHub-shaped events) +│ ├── types.ts # Provider interface (matches/verify/parse) +│ ├── hmac.ts # HMAC-SHA256 + timing-safe compare helpers +│ ├── index.ts # detectProvider() registry (github, gitea) +│ ├── github/ # X-GitHub-Event + X-Hub-Signature-256 ("sha256=" prefix) +│ │ ├── verify.ts # HMAC signature verify +│ │ └── parse.ts # parseEvent (headers + body → WebhookEvent) +│ └── gitea/ # X-Gitea-Event + X-Gitea-Signature (plain hex HMAC) +│ ├── verify.ts # HMAC signature verify (no prefix) +│ └── parse.ts # parse + normalize Gitea payloads to GitHub shape ├── formatters/ # Platform-neutral message formatters (was formatter.ts) │ ├── index.ts # formatEvent: 28-event switch → NeutralMessage + re-exports │ ├── colors.ts # GITHUB_COLORS + WORKFLOW_CONCLUSION_EMOJI @@ -76,11 +85,13 @@ src/__tests__/ # bun test unit tests (webhook, formatter, discord, te ## Responsibilities -- Verify GitHub webhook signatures (Web Crypto HMAC-SHA256) +- Verify GitHub webhook signatures (Web Crypto HMAC-SHA256, `X-Hub-Signature-256`) +- Verify Gitea webhook signatures (Web Crypto HMAC-SHA256, plain hex `X-Gitea-Signature`) +- Normalize Gitea webhook payloads to a GitHub-shaped `WebhookEvent` (push `compare_url` → `compare`, `pull_request_comment` → `pull_request_review_comment`, ...) - Verify Discord interactions (Web Crypto Ed25519, X-Signature-Ed25519 over timestamp + body) - Verify Telegram webhook calls (X-Telegram-Bot-Api-Secret-Token when configured) - Filter events by: event type, repo name, actor, action, branch, keyword (regex supported) -- Filter routes by group owner restriction (`Group.owners`) and skip fallback routes whenever a regular route matched; stop evaluating further routes when a matched route has `stop: true` +- Filter routes by group owner restriction (`Group.owners`), group source-platform restriction (`Group.providers`: github/gitea), and skip fallback routes whenever a regular route matched; stop evaluating further routes when a matched route has `stop: true` - Mention Discord roles on route trigger: route-level `discordRoleIds` are rendered as `<@&id>` into the Discord message `content` (Telegram targets ignore the field) - Format 28 event types as platform-neutral messages (Discord embeds + Telegram HTML) - Route messages to Discord channels/threads and Telegram chats/topics via REST @@ -135,6 +146,7 @@ Rule: no functional change ships without its documentation; docs and code must n - **D1 database**: Binding `DB` (database `webhooker`, id `214a0104-3235-47c0-b7bf-ddda95f3c8ac`) for `send_logs` + `discord_links` + `telegram_links` tables - **Discord**: `DISCORD_PUBLIC_KEY` (Interactions Endpoint signature verification, from Discord Developer Portal) and `DISCORD_APPLICATION_ID` (optional, auto-resolved via `GET /oauth2/applications/@me` when omitted) are required for interactions - **Telegram**: `TELEGRAM_TOKEN` (Bot API token from BotFather) required for Telegram routes; `TELEGRAM_WEBHOOK_SECRET` (optional secret token for `POST /telegram/webhook` verification); avatars are sent as a link-preview card via the built-in `GET /api/richheader` (overridable with `TELEGRAM_RICH_HEADER_HOST`) +- **Webhook providers**: `GITEA_WEBHOOK_SECRET` (required to receive Gitea webhooks; Gitea signs `X-Gitea-Signature` with the hex HMAC-SHA256 of the body) ## Deployment @@ -150,7 +162,8 @@ npm run db:migrate:prod # wrangler d1 migrations apply webhooker --remote (mig npx wrangler deploy ``` -Full list of secrets used: `GITHUB_WEBHOOK_SECRET`, `GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY` +Full list of secrets used: `GITHUB_WEBHOOK_SECRET`, `GITEA_WEBHOOK_SECRET`, +`GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY` (PKCS#8 PEM), `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `DISCORD_TOKEN`, `DISCORD_PUBLIC_KEY`, `TELEGRAM_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, `ADMIN_USER_IDS`, plus optional `BASE_URL`, `DISCORD_APPLICATION_ID`, `TELEGRAM_RICH_HEADER_HOST`, diff --git a/README.md b/README.md index 6f5436f..6748e72 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # WebHooker -GitHub webhook → Discord / Telegram dispatcher. Receives webhook events via Cloudflare Workers, applies filters, and routes formatted messages to Discord channels/threads and Telegram chats/topics. +GitHub / Gitea webhook → Discord / Telegram dispatcher. Receives webhook events via Cloudflare Workers, applies filters, and routes formatted messages to Discord channels/threads and Telegram chats/topics. Forge-specific adapters live under `src/providers/` (GitHub + Gitea today; GitLab etc. can be added later). ## Features - **28 event formatters** — push, pull_request, issues, issue_comment, workflow_run, workflow_job, status, deployment, deployment_status, check_run, check_suite, ping, release, create, delete, star, fork, pull_request_review, pull_request_review_comment, commit_comment, member, label, milestone, discussion, discussion_comment, repository, code_scanning_alert, dependabot_alert (+ generic fallback) +- **Multi-provider webhooks** — GitHub (`X-Hub-Signature-256`) and Gitea (`X-Gitea-Signature`) share one `/webhook` endpoint; the provider is auto-detected from headers - HMAC-SHA256 signature verification (Web Crypto API) - Filter by event type, repo, actor, action, branch, keyword (supports regex) - Rich messages with color coding, author avatars, fields, and timestamps — rendered as Discord embeds and Telegram HTML @@ -51,6 +52,7 @@ npx wrangler dev # Start local dev server | Variable | Description | | --------------------------- | ---------------------------------------------------------------------------------------------- | | `GITHUB_WEBHOOK_SECRET` | Webhook secret from GitHub | +| `GITEA_WEBHOOK_SECRET` | Webhook secret from Gitea (required only to receive Gitea webhooks) | | `GITHUB_APP_ID` | GitHub App ID (not currently used by the code; kept for compatibility) | | `GITHUB_PRIVATE_KEY` | App private key (PKCS#8 PEM; not currently used by the code; kept for compatibility) | | `GITHUB_CLIENT_ID` | OAuth client ID | @@ -104,7 +106,7 @@ Set `discordRoleIds` on a route to ping Discord roles (身份组) whenever it fi } ``` -Routes belong to **groups** (KV `config:groups`) that scope admin access and can restrict which org/user events flow in. See `config.example.yaml` and `docs/guide/configuration.md` for the full schema. +Routes belong to **groups** (KV `config:groups`) that scope admin access and can restrict which org/user events flow in — including which source platform (`providers`: `github` / `gitea`). See `config.example.yaml` and `docs/guide/configuration.md` for the full schema. ### Web UI (`/admin`) diff --git a/README.zh.md b/README.zh.md index aeadfaf..9d555d8 100644 --- a/README.zh.md +++ b/README.zh.md @@ -1,10 +1,11 @@ # WebHooker -GitHub webhook → Discord / Telegram 分发服务。通过 Cloudflare Workers 接收 webhook 事件,应用过滤器,将格式化消息路由到 Discord 频道/子区与 Telegram 群组/话题。 +GitHub / Gitea webhook → Discord / Telegram 分发服务。通过 Cloudflare Workers 接收 webhook 事件,应用过滤器,将格式化消息路由到 Discord 频道/子区与 Telegram 群组/话题。各 forge 适配器位于 `src/providers/`(目前支持 GitHub + Gitea;GitLab 等可后续扩展)。 ## 功能特性 - **28 种事件格式化** — push、pull_request、issues、issue_comment、workflow_run、workflow_job、status、deployment、deployment_status、check_run、check_suite、ping、release、create、delete、star、fork、pull_request_review、pull_request_review_comment、commit_comment、member、label、milestone、discussion、discussion_comment、repository、code_scanning_alert、dependabot_alert(+ 通用回退) +- **多提供方 webhook** — GitHub(`X-Hub-Signature-256`)与 Gitea(`X-Gitea-Signature`)共用 `/webhook` 端点,按请求头自动识别来源 - HMAC-SHA256 签名验证(Web Crypto API) - 按事件类型、仓库、操作人、操作、分支、关键词(支持正则)过滤 - 富消息:颜色编码、作者头像、字段、时间戳——渲染为 Discord embed 与 Telegram HTML @@ -51,6 +52,7 @@ npx wrangler dev # 启动本地开发服务器 | 变量 | 说明 | | --------------------------- | --------------------------------------------------------------------------- | | `GITHUB_WEBHOOK_SECRET` | GitHub webhook 密钥 | +| `GITEA_WEBHOOK_SECRET` | Gitea webhook 密钥(仅接收 Gitea webhook 时需要) | | `GITHUB_APP_ID` | GitHub App ID(当前代码未使用,为兼容保留) | | `GITHUB_PRIVATE_KEY` | App 私钥(PKCS#8 PEM;当前代码未使用,为兼容保留) | | `GITHUB_CLIENT_ID` | OAuth Client ID | @@ -104,7 +106,7 @@ npx wrangler dev # 启动本地开发服务器 } ``` -路由隶属于**分组**(KV `config:groups`),分组用于限定管理权限,并可限制哪些组织/用户的事件流入。完整模式见 `config.example.yaml` 与 `docs/zh/guide/configuration.md`。 +路由隶属于**分组**(KV `config:groups`),分组用于限定管理权限,并可限制哪些组织/用户的事件流入——包括来源平台(`providers`:`github` / `gitea`)。完整模式见 `config.example.yaml` 与 `docs/zh/guide/configuration.md`。 ### Web 控制台(`/admin`) diff --git a/admin/components/GroupEditor.vue b/admin/components/GroupEditor.vue index 8d878f5..3723000 100644 --- a/admin/components/GroupEditor.vue +++ b/admin/components/GroupEditor.vue @@ -56,6 +56,31 @@ />
{{ t("groupEditor.ownersHint") }}
+
+ +
+ + +
+
{{ t("groupEditor.providersHint") }}
+