makeplane / makeplane/developer-docs

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

Ouverte Adaptée aux débutants
#261 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Langage dominant
JavaScript
Étoiles
16
Forks
23
Merge moyen
46 min
PR mergées (30 j)
1

Description

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.

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Repérez le guide de configuration de l’intégration GitHub pour le self-hosting et lisez la section "Create GitHub App" autour de l’étape 7, y compris les instructions existantes concernant l’URL du webhook. Ajoutez l’étape requise Webhook Secret avec la valeur WEBHOOK_SECRET et expliquez l’effet d’une incohérence ; le travail est terminé lorsque le guide couvre clairement la configuration de la synchronisation des issues et des PRs, sans s’étendre à la suggestion facultative de vérification de l’état de l’UI.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
github
Domaine
documentation
Type d'issue
Documentation
Difficulté
1/5
Temps estimé
1-3 heures
Activité
Calme
Clarté
Clairement spécifiée
Accessibilité débutants
75/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.