Validate Pr Review App

validate-pr-review-app is a self-hosted GitHub App. It receives pull_request_review and pull_request webhooks, fetches the PR's reviews and commits via the GitHub API, validates the reviews, and reports the result as a GitHub Check. A PR needs at least 1 approval, and 2 approvals when a committer approves it or when the PR contains unsigned commits, commits not linked to a GitHub user, or commits from untrusted Machine Users or GitHub Apps.

Don't read every reference file. Read only the one that matches the task.

Gotchas

• trust.trusted_apps doesn't support glob or regular expressions. A name containing ., *, ?, ^, +, or $ makes the app fail at startup. trust.untrusted_machine_users does support glob, and a leading ! marks a machine user as trusted (like .gitignore).
• Trust configuration is replaced, not merged, between the repository, global, and default levels. Setting trust.trusted_apps without listing renovate and dependabot makes them untrusted, because it replaces the default. trusted_apps and untrusted_machine_users are resolved independently of each other.
• Only the first repositories element matching the repository is used. The remaining matching elements are ignored.
• insecure.allow_unsigned_commits: true combined with unsigned_commit_apps or unsigned_commit_machine_users makes the app fail at startup. Use one or the other.
• A repository with ignored: true gets no check at all, so a required status check on it never becomes successful.

Understanding and troubleshooting

• Validation Rules — what the app validates and when a PR passes or fails.
• Why are 2 approvals required for a pull request? — to explain or troubleshoot a PR that needs two approvals, including a check that stays pending.
• How To Avoid 2 Approvals — to reduce a PR's approval requirement, including using CSM Actions for automatic code fixes and approvals.
• How It Works — to understand the overall mechanism and the webhook flow.
• Allow Empty Commits and Trivial Merge Commits — when an empty commit or an "update branch" merge commit unexpectedly does or doesn't require a second approval.
• Handling Pull Request Events — when no check is created after pushing a commit to an already-approved PR.
• Merge Queue Support — when the repository uses a merge queue.

Configuration

• Configuration — to change configuration (trusted_apps, untrusted_machine_users, trust priority between repository/global/default config, check_name, log_level, insecure unsigned-commit rules) or to validate a config file with its JSON Schema.
• Environment Variables — to configure how the app process runs (CONFIG, CONFIG_FILE, PORT, SECRET_FILE, etc.).
• Secrets — to set up webhook_secret and github_app_private_key, and to choose a secret source (env var, file, AWS Secrets Manager, Google Secret Manager).
• Customize footer — to customize the footer shown on the Checks tab.

Setup and operation

• GitHub App Settings — to register the GitHub App with the right permissions and event subscriptions.
• Getting Started - HTTP Server — to run the app locally as an HTTP server and receive webhooks via smee.io. Also lists the HTTP endpoints.
• Getting Started - AWS Lambda — to deploy the app to AWS Lambda with Terraform, using a Function URL or Amazon API Gateway.
• Logging, Monitoring, and Security — to run the app in production, and to read or alert on its JSON logs.
• Verify Release Assets — to verify downloaded release assets with GitHub CLI, slsa-verifier, or Cosign.
• Verify Container Images — to verify container images with Cosign.