makeplane / makeplane/developer-docs

GitHub integration setup guide is missing the webhook secret configuration step, causes silent failure of all webhook processing

Đang mở Phù hợp với người mới
#261 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Ngôn ngữ chính
JavaScript
Star
16
Fork
23
Merge trung bình
46 phút
Pull request đã merge (30 ngày)
1

Mô tả

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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Tìm hướng dẫn thiết lập tích hợp GitHub cho self-hosting và đọc phần "Create GitHub App" quanh bước 7, bao gồm các hướng dẫn hiện có về URL webhook. Thêm bước Webhook Secret bắt buộc với giá trị WEBHOOK_SECRET và giải thích ảnh hưởng của việc không khớp; được coi là hoàn tất khi hướng dẫn trình bày rõ việc thiết lập đồng bộ hóa issue và PR mà không mở rộng sang đề xuất kiểm tra tình trạng UI tùy chọn.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
github
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
1/5
Thời gian dự kiến
1-3 giờ
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
75/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.