GitHub integration setup guide is missing the webhook secret configuration step, causes silent failure of all webhook processing
还没有人认领这个 Issue。
评估
- 难度
- 1/5
- 预计耗时
- 1-3 小时
- 新手友好度
- 75/100
- Issue 类型
- 文档
- 描述清晰度
- 描述清楚
- 活跃度
- 冷清
- 技术栈
- github
调研方向
找到 self-hosting 的 GitHub 集成设置指南,并阅读第 7 步附近的“Create GitHub App”部分,包括现有的 webhook URL 说明。添加必需的 Webhook Secret 步骤,并使用值 WEBHOOK_SECRET,解释不匹配的影响;完成标准是指南清楚地涵盖 issue 和 PR 同步的设置,而不扩展到可选的 UI 健康检查建议。
由索引模型根据 Issue 内容生成。
描述
The self-hosting GitHub integration setup guide walks users through creating a GitHub App and configuring the webhook URL, but does not document that the GitHub App's Webhook Secret field must be set to match the instance's WEBHOOK_SECRET environment variable (default: plane-silo).
Without this configuration, silo's HMAC-SHA256 signature verification silently fails for every incoming webhook. The webhook endpoint returns 202 (accepted) and logs the arrival, but no downstream processing occurs. No error is logged. There is no UI indication that anything is wrong — the integration appears correctly configured (workspace connected, entity sync enabled, PR state mapping saved) but no sync actually happens.
Impact:
I spent approximately 14 hours over two sessions debugging this exact issue before discovering the undocumented webhook secret requirement. I tried rotating credentials, fixing URL schemes (http→https in multiple env vars and oauth_applications table rows), re-encoding private keys, container recreation, database state verification, and numerous other paths before realizing the webhook secret field on the GitHub App side was empty while silo expected a matching value.
The failure mode is particularly hard to diagnose because:
Setup appears successful at every visible step
Silo logs the webhook arrival ("Github Webhook Payload") and returns 202
No error is surfaced anywhere — to users or to admins
Signature verification failure is not logged
Proposed documentation change:
In the "Create GitHub App" section, after the "Webhook URL" step (step 7), add a new step:
Webhook Secret (Required)
In the Webhook section, set the Secret field to match your Plane instance's WEBHOOK_SECRET environment variable. The default value is plane-silo.
Without a matching webhook secret, silo's signature verification will silently reject every incoming webhook and the integration will appear working but produce no sync activity. This is required for both issue and PR sync to function.
Additional suggestion:
Consider surfacing a health check or warning in the Plane UI when webhooks are arriving at silo but failing signature verification. Silent-drop failure modes are very difficult for users to self-diagnose.
- 主要语言
- JavaScript
- 星标
- 16
- 派生
- 23
- 平均合并
- 46 分钟
- 30 天内合并 PR
- 1
贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
makeplane/developer-docs 的其他 Issue
-
难度 2/5 1-3 小时 新手友好度 78/100
makeplane/developer-docs#269 ·
-
难度 2/5 1-3 小时 新手友好度 72/100
makeplane/developer-docs#262 ·
-
难度 4/5 3-5 天 新手友好度 35/100
makeplane/developer-docs#181 ·
查看 makeplane/developer-docs 的全部 Issue
相似的 Issue
-
bug
难度 2/5 1-3 小时 新手友好度 76/100
avniproject/avni-client#2135 ·
-
automated broken-link
难度 1/5 1 小时以内 新手友好度 85/100
-
agent/security hive/hosted-available-lke648397-260827-5n31 security
难度 2/5 1-3 小时 新手友好度 84/100
-
enhancement
难度 2/5 1-3 小时 新手友好度 70/100
babalae/bettergi-scripts-list#3674 ·
-
A-Release-Notes C-Editing D-Modest S-Ready-For-Implementation
难度 2/5 1-3 小时 新手友好度 72/100
bevyengine/bevy-website#2595 ·