Stenographer.AI

Setup Guide

How to configure?

This page turns documents/github_app_setup.md into a production-friendly setup guide for Stenographer.AI. Follow it when you want GitHub App auth, webhook delivery, and repository installation to work together cleanly.

What this covers

Configure the GitHub App first, then install it on repositories.

Stenographer.AI needs two layers of setup. First, you define the GitHub App itself at the account or organization level. Then you install that app on the repositories you actually want to monitor. Both layers have to be correct before pull request webhooks will arrive reliably.

1. GitHub App settings

Create the app under GitHub Developer Settings.

Navigate to Settings → Developer settings → GitHub Apps → New GitHub App and fill in the base configuration below.

General configuration

GitHub App Name

Stenographer AI

Use a clear, user-facing name so teams can recognize it during installation.

Homepage URL

https://stenographer.ai

For local testing, use your local app URL instead.

Callback URL

https://your-domain.com/api/auth/callback/github

Required for GitHub login through NextAuth.

Request user authorization during installation

Enabled

Turn this on so OAuth is available when the app is installed.

Webhook configuration

Webhook active

Enabled

GitHub must be allowed to send webhook deliveries to Stenographer.AI.

Webhook URL

https://your-domain.com/api/webhooks/github

For local development, this must be a public tunnel URL such as ngrok.

Webhook secret

Use a strong random string

Store the same value as GITHUB_WEBHOOK_SECRET in your environment.

2. Permissions and events

Keep permissions minimal but sufficient.

Stenographer.AI only needs a small set of repo permissions. The goal is enough access to read diffs, understand PR context, and post summaries back to GitHub.

Permission
Level
Why it is needed
Contents
Read-only
Needed to fetch PR diffs and inspect repository content.
Pull requests
Read and write
Needed to read PR metadata and publish AI-generated summaries as comments.
Metadata
Read-only
Required by GitHub and granted by default.

Event subscription

  • Subscribe to the Pull request event.
  • This is what triggers webhook deliveries for opened, synchronized, closed, and merged pull requests.

3. Credentials and environment

Map every GitHub-generated credential to the right environment variable.

After the app is created, GitHub will show or generate the values below. Save them immediately and wire them into your deployment environment before you test login or webhook delivery.

App ID

GITHUB_APP_ID

Found on the main GitHub App settings page.

Client ID

GITHUB_ID

Found in the GitHub App OAuth section.

Client Secret

GITHUB_SECRET

Generate this in GitHub and add it to your app environment.

Webhook Secret

GITHUB_WEBHOOK_SECRET

Must exactly match the webhook secret configured in GitHub.

Private Key (.pem)

GITHUB_APP_PRIVATE_KEY

Generate and download the private key from the GitHub App page.

4. Local development setup

If you want to test locally, use localhost for auth and a tunnel for webhooks.

GitHub can redirect a browser back to your local app, but it cannot deliver webhook payloads to localhost. The clean setup is to keep the app itself on http://localhost:3000 and expose that local server through a tunnel for webhook delivery.

What to do locally

  1. 1Run Stenographer.AI locally on http://localhost:3000.
  2. 2Set NEXTAUTH_URL to http://localhost:3000 so GitHub login redirects back correctly.
  3. 3Set the GitHub App callback URL to http://localhost:3000/api/auth/callback/github.
  4. 4Expose your local app with a public tunnel such as ngrok or Cloudflare Tunnel.
  5. 5Use that public tunnel URL for the GitHub App webhook URL because GitHub cannot reach localhost directly.
  6. 6Keep the webhook secret in sync between GitHub and GITHUB_WEBHOOK_SECRET locally.

Useful local values

NEXTAUTH_URL

http://localhost:3000

GITHUB_ID

GitHub App client ID

GITHUB_SECRET

GitHub App client secret

GITHUB_APP_ID

GitHub App ID

GITHUB_APP_PRIVATE_KEY

The downloaded .pem private key contents

GITHUB_WEBHOOK_SECRET

The same secret configured in the GitHub App webhook settings

Example local webhook flow

Start the app with npm run dev, open a tunnel that points to port 3000, put that tunnel URL into the GitHub App webhook field, and keep the callback URL pointed at http://localhost:3000/api/auth/callback/github. Browser login will return to localhost, while webhook deliveries will hit the public tunnel and forward into your local Next.js server.

5. Repository installation

Installing the app is what actually turns webhook delivery on.

Installation flow

  1. 1Open the public GitHub App page and click Install.
  2. 2Choose the organization or personal account that owns the repository.
  3. 3Pick either All repositories or Only select repositories.
  4. 4If you choose Only select repositories, explicitly select the repos Stenographer.AI should process.

Repository prerequisites

  • The repository must not be archived.
  • The webhook endpoint must stay reachable and return successful responses.
  • If deliveries repeatedly fail, GitHub may suspend the webhook automatically.
  • To receive merge-related activity, the repository must actually be using pull requests.

Final sanity check

If pull requests are not appearing in Stenographer.AI, the most common causes are a missing webhook secret, the app not being installed on the target repository, a suspended webhook due to delivery failures, or missing pull request permissions.

The source material for this page still lives in documents/github_app_setup.md, but this version is formatted for direct in-product reading.

Back to LicenseBack to Home