While reading the setup documentation as a first-time contributor, I did not realize that running the application locally requires temporarily exposing my laptop to the public internet in order to receive GitHub webhooks.
The Prerequisites section immediately instructs contributors to create a GitHub App and configure ngrok, but it does not explain:
- why GitHub cannot communicate with localhost,
- that ngrok is used to create a temporary public HTTPS endpoint,
- that this setup is only required when testing GitHub authentication, webhook handling, and PR automation features.
This lack of explanation makes onboarding intimidating and may discourage new contributors who do not need full GitHub integration to get started.
Consider splitting the setup into two clearly labeled paths:
A) Basic local testing — for UI, documentation, and admin-level changes, without GitHub App or ngrok.
B) Advanced GitHub-integrated testing — for contributors working on authentication, PR status automation, and webhook processing.
This separation would make onboarding clearer and lower the barrier to entry.
### Preview of proposed Document change
How local testing works
- This application is implemented as a GitHub App, which means GitHub must be able to send webhook events (e.g. pull request updates, CLA status changes) to the running server.
- GitHub can only deliver these events to publicly accessible HTTPS endpoints — it cannot communicate directly with localhost.
- For this reason, tools such as ngrok are used to temporarily expose your local development server to the public internet when testing GitHub integration features.
- This setup is optional unless you are working on GitHub authentication, webhook handling, or PR automation.
If this direction looks reasonable, I would be happy to submit a pull request implementing these documentation changes.
While reading the setup documentation as a first-time contributor, I did not realize that running the application locally requires temporarily exposing my laptop to the public internet in order to receive GitHub webhooks.
The Prerequisites section immediately instructs contributors to create a GitHub App and configure ngrok, but it does not explain:
This lack of explanation makes onboarding intimidating and may discourage new contributors who do not need full GitHub integration to get started.
Consider splitting the setup into two clearly labeled paths:
A) Basic local testing — for UI, documentation, and admin-level changes, without GitHub App or ngrok.
B) Advanced GitHub-integrated testing — for contributors working on authentication, PR status automation, and webhook processing.
This separation would make onboarding clearer and lower the barrier to entry.
### Preview of proposed Document change
How local testing works
If this direction looks reasonable, I would be happy to submit a pull request implementing these documentation changes.