makeplane / makeplane/developer-docs
GitHub integration setup guide is missing the webhook secret configuration step, causes silent failure of all webhook processing
まだ誰も着手していません。
- 主要言語
- JavaScript
- スター
- 16
- フォーク
- 23
- 平均マージ
- 46分
- マージ済み PR(30日)
- 1
説明
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.
コントリビューションガイド
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
調査の方向性
セルフホスティング向けの GitHub 統合セットアップガイドを見つけ、手順 7 前後の「Create GitHub App」セクションを、既存の Webhook URL に関する手順も含めて確認してください。WEBHOOK_SECRET の値を使用する、必要な Webhook Secret の手順を追加し、不一致が発生した場合の影響を説明してください。ガイドで issue と PR の同期のセットアップが明確に説明され、オプションの UI ヘルスチェックの提案にまで話を広げていなければ完了です。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- github
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 1/5
- 見積もり時間
- 1〜3時間
- 活発さ
- 静か
- 明瞭さ
- 明確に書かれている
- 初心者へのやさしさ
- 75/100