makeplane / makeplane/developer-docs

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

Abierto Apto para principiantes
#261 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Lenguaje dominante
JavaScript
Estrellas
16
Forks
23
Merge medio
46 min
PR fusionados (30 d)
1

Descripción

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.

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Línea de trabajo

Localiza la guía de configuración de la integración de GitHub para self-hosting y lee la sección "Create GitHub App" alrededor del paso 7, incluidas las instrucciones existentes sobre la URL del webhook. Añade el paso requerido de Webhook Secret con el valor WEBHOOK_SECRET y explica el efecto de una discrepancia; se considera terminado cuando la guía cubra claramente la configuración para la sincronización de issues y PRs sin extenderse hacia la sugerencia opcional de comprobación de salud de la UI.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
github
Área
documentation
Tipo de issue
Documentación
Dificultad
1/5
Tiempo estimado
1-3 horas
Estado de actividad
Tranquilo
Claridad
Bien especificado
Aptitud para principiantes
75/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.