Skip to content

Clarification of local development requirements and separation of basic vs GitHub-integrated testing #16

Description

@agrim-git-hub

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:

  1. why GitHub cannot communicate with localhost,
  2. that ngrok is used to create a temporary public HTTPS endpoint,
  3. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions