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

Open
  • Is something wrong?
#16 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
48/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
github, python
Domain
documentation

Research direction

Start in the setup documentation's Prerequisites section and separate the existing local setup guidance into basic local testing and advanced GitHub-integrated testing. Explain localhost, ngrok, and the optional nature of GitHub App configuration using the proposed wording. Done means contributors can identify which setup path applies to their work without changing application behavior.

Written by the indexing model from the issue text.

Description

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.

Dominant language
Python
Stars
8
Forks
15
Avg merge
7m
Merged PRs (30d)
1

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from psf/clabot

All issues in psf/clabot

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.