mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-08-29 04:26:38 +00:00
52 lines
3.0 KiB
Markdown
52 lines
3.0 KiB
Markdown
# @deepseek-ai/dsh-webhook-github
|
|
|
|
English | [中文](README.zh.md)
|
|
|
|
`dsh-webhook-github` registers one exact HTTP route on the injected `ctx.webServer`. It bounds and verifies GitHub's raw JSON body, projects a provider-neutral delivery, calls `ctx.webhookRuntime.dispatch()`, and returns `202` without waiting for rules or Sessions.
|
|
|
|
## Configuration
|
|
|
|
| Key | Meaning |
|
|
|---|---|
|
|
| `source` | Non-empty adapter instance carried to rules, such as `primary-github`. |
|
|
| `path` | Exact non-root pathname without trailing slash, query, or fragment. |
|
|
| `secretEnv` | Credential reference containing the GitHub webhook secret. |
|
|
| `maxBodyBytes` | Positive safe-integer ceiling for the untouched request body. |
|
|
|
|
All fields are required. The secret reference is resolved for every request, so rotation affects the next delivery without reloading the plugin.
|
|
|
|
## HTTP contract
|
|
|
|
Only `POST application/json` is accepted. The adapter reads a bounded UTF-8 body, requires `X-Hub-Signature-256`, `X-GitHub-Delivery`, and `X-GitHub-Event`, resolves the secret, verifies HMAC before JSON parsing, and requires a top-level lossless-JSON object. It never logs the secret, signature, or payload.
|
|
|
|
| Status | Meaning |
|
|
|---|---|
|
|
| `202` | Verified JSON was dispatched in memory. |
|
|
| `400` | Required header, UTF-8, JSON, or top-level object was invalid. |
|
|
| `401` | Signature was missing or invalid. |
|
|
| `405` | Method was not `POST`. |
|
|
| `413` | Declared or streamed body exceeded `maxBodyBytes`. |
|
|
| `415` | Media type was not `application/json`. |
|
|
| `503` | Credential or webhook runtime was unavailable. |
|
|
|
|
`202` does not state that any rule matched or that a Session was created. GitHub event-specific field validation belongs to each rule; the adapter guarantees only authenticated generic JSON.
|
|
|
|
## Dedicated listener composition
|
|
|
|
The normal Web profile already owns `ctx.webServer`. Mount another `dsh-host-webserver` and this adapter inside a group that isolates only `webServer`; the adapter still inherits credentials and `webhookRuntime`. The [GitHub review example](../../../examples/web-github-review/README.md) uses `127.0.0.1:3081/github` behind a TLS reverse proxy while the UI remains on port 3080.
|
|
|
|
## Model Experience
|
|
|
|
Indirectly, through `dsh-webhook`: this adapter contributes no prompt or tool schema; a matching rule owns the Session request and model-visible text.
|
|
|
|
#### KV Cache effect
|
|
|
|
Independent. Authentication and HTTP dispatch do not touch a model request; any new Session prefix belongs to the consuming rule and runtime.
|
|
|
|
## Known Limitations and Deferred Work
|
|
|
|
- **No TLS** — the injected development WebServer is normally loopback-only behind a TLS reverse proxy or tunnel.
|
|
- **Generic payload validation only** — rules own validation of the GitHub event fields they consume.
|
|
- **No provider acknowledgement of downstream work** — `202` precedes arbitrary rule calls and Session creation.
|
|
- **No form encoding** — GitHub must send `application/json`; `application/x-www-form-urlencoded` is rejected.
|