GitHub App Guide

Installing, configuring, and troubleshooting the PRCheck GitHub App.

Permissions required

PRCheck requests the minimum permissions needed to post review comments and read PR diffs. Here is exactly what is requested and why:

permissions 
pull_requests: read     # read PR metadata + diff
checks:        write    # post status check results
contents:      read     # read file diff content

PRCheck does NOT request: administration, members, metadata: write, or any organization-level permissions. We never request write access to repository contents.

Install flow

  1. Go to your PRCheck dashboard and click "Connect GitHub".
  2. You are redirected to GitHub's app authorization page. Review permissions and click "Authorize PRCheck".
  3. On the next screen, choose to install on all repositories or select specific repos. You can change this later in your GitHub organization settings.
  4. You are redirected back to your PRCheck dashboard. Newly connected repositories appear within 30 seconds.
  5. Enable scanning per-repo from the dashboard by toggling the repo on.

If you have a GitHub organization with multiple members, you need organization admin permissions to install a GitHub App. If you do not have admin access, request installation from your GitHub organization owner.

Webhook events

PRCheck subscribes to these GitHub webhook events on installation:

events 
pull_request:
  - opened         # new PR: trigger full scan
  - synchronize    # new commits pushed: re-scan changed files
  - reopened       # re-opened PR: trigger scan

check_suite:
  - rerequested    # manual re-run from GitHub UI

Events for closed or merged PRs are ignored. Comment edits and review approvals do not trigger scans.

Rate limits

PRCheck uses GitHub's installation-level API token for posting check results and review comments. GitHub allows 5,000 API requests per hour per installation. For most teams this is not a bottleneck; a typical PR scan uses 3-4 API calls (check create, comment writes, check complete).

For very large organizations with high PR volume (100+ PRs/hour), contact us to discuss priority queue routing at [email protected].

Troubleshooting common install issues

PRCheck is not commenting on new PRs

  • Verify the repo is toggled ON in your PRCheck dashboard.
  • Check that the GitHub App installation includes the specific repo (GitHub Organization Settings > Installed Apps > PRCheck > Repository access).
  • Check the webhook delivery log in GitHub (Organization Settings > Webhooks or the App installation page) for failed deliveries.

Status check shows "PRCheck (skipped)"

  • This happens when the PR has no files in the repo's configured scope (e.g., only docs files when your ruleset excludes docs/).
  • Skipped scans count as passed status checks.

Review comments appear twice

  • This can happen if the same repo is connected to multiple PRCheck accounts. Remove duplicate connections from both dashboards and reconnect with one account.

"Installation suspended" error

  • The GitHub App installation has been suspended, usually due to a payment issue or org policy change. Go to your PRCheck dashboard and reconnect.