PRNote GitHub App

A self-hosted GitHub App version of prnote-action. On pull_request.opened, it reads commits and changed-file patches through GitHub's API, writes the canonical <branch>: pull request title and commit-message body, and can add one managed rich-summary comment. It never checks out or executes pull-request code.

Create the GitHub App

In GitHub, open Settings → Developer settings → GitHub Apps → New GitHub App and configure:

• Webhook URL: https://your-host/api/github/webhooks
• Marketplace webhook URL (Payload URL): https://your-host/webhooks/marketplace
• Webhook secret: a long random value also used as GITHUB_WEBHOOK_SECRET
• Repository permissions: Contents: Read-only, Pull requests: Read and write, Issues: Read and write only when PRNOTE_COMMENT=true
• Subscribe to: Pull request on the main webhook URL, and Marketplace purchase on the marketplace webhook URL
• Where can this app be installed?: choose the scope you need

After creating it, note the App ID, generate a private key, and install the app on the desired repositories.

Run locally

Requires Node.js 20 or newer.

cp .env.example .env
npm install
npm run dev

GitHub must be able to reach the webhook URL, so expose port 3000 with a trusted tunnel for local development. The app automatically loads .env from its working directory. Variables already provided by the hosting platform take precedence.

Configuration

Required variables are GITHUB_APP_ID, GITHUB_PRIVATE_KEY, and GITHUB_WEBHOOK_SECRET. A PEM key can contain literal newlines or escaped \\n sequences. GEMINI_API_KEY is optional; when absent or on provider failure, commit-history fallback generation is used.

Behavior matches the action defaults: title/body updates and overwrite are enabled, rich comments are disabled, maximum diff context is 20,000 characters, timeout is 120 seconds, language is en, and model is gemini-3.5-flash. See .env.example for variable names. Set PRNOTE_EXCLUDE to a comma-separated replacement for the default exclusions.

Deploy

Build and run directly:

npm install
npm run build
npm start

Or use the included Dockerfile. The service exposes GET /health, expects GitHub pull request webhooks at POST /api/github/webhooks, and GitHub Marketplace purchase events at POST /webhooks/marketplace. Run one instance for this MVP: webhook work is performed in-process after the HTTP acknowledgment, with no durable job queue or delivery deduplication. Commit a generated package-lock.json and switch deployment installs to npm ci when dependencies can be downloaded in your environment.

Security notes

• Webhook signatures are checked with HMAC-SHA256 before JSON parsing.
• GitHub installation tokens are short-lived and created per webhook invocation.
• Gemini receives PR metadata and selected patches, subject to the configured exclusions and character limit.
• Do not expose the private key, webhook secret, Gemini key, or .env file.