Installing the GitHub App
CrossCheck reviews PRs through a GitHub App installation on your account or organization. One install covers any number of repos.
Install
- From your CrossCheck org, open Settings (or click Install GitHub App on the empty repos page).
- You'll be redirected to GitHub. Choose the account or organization to install on.
- Pick All repositories or Only select repositories and choose which ones CrossCheck can see.
- Click Install. GitHub redirects you back to CrossCheck.
You can change the repo selection at any time from the GitHub App settings page on GitHub — CrossCheck picks up the change immediately.
What CrossCheck can do
The GitHub App requests the following permissions:
| Permission | Why |
|---|---|
| Read access to Contents | Clone the repo into a sandbox to evaluate checks against the diff. |
| Read & write Pull requests | Post and update the sticky review comment; resolve inline threads on re-runs. |
| Read & write Checks | Post the CrossCheck check that shows on the PR while a review runs. |
| Read & write Issues | Post inline review comments in general-review mode. |
| Read access to Metadata | List installation repos and resolve default branches. |
CrossCheck subscribes to the pull_request and push webhooks. pull_request events trigger reviews; push to your default branch refreshes the cached cross-check.yaml config when that file is touched.
What CrossCheck never does
- Create new branches in your repo.
- Push commits or force-push.
- Merge PRs unless you opt in to
pass_behavior: approve_and_mergeper repo. Branch protection still gates the actual merge. - Run with a long-lived token. Every review mints a fresh 1-hour installation token, scoped to the single repo being reviewed, and revokes it when the run ends.
See Security and data handling for sandbox isolation and secret scrubbing.
After install
CrossCheck checks for an installation on every PR webhook. If the org has installed the App and the repo is in scope, the PR is reviewed.
Pages that read live PR data (the repo overview, the PRs tab, the PR detail page) all use a fresh installation token per request — nothing is cached or stored long-term.
Verifying the install
From your org's Settings page, the GitHub section shows:
- Installed on
<account>when the install is healthy. - Not installed if the App was removed on GitHub, or never installed.
If you're seeing Not installed but you definitely installed the App, the most likely cause is that the GitHub admin restricted the App's repo selection to exclude the repo you're trying to use. Open the GitHub App settings on GitHub and add the repo to the selection.
Uninstalling
Uninstall from GitHub: Settings → Integrations → Applications → CrossCheck → Configure → Uninstall.
After uninstall:
- New PR webhooks stop being received — no further reviews run.
- Historical runs, check groups, and
cross-check.yamlcache remain in CrossCheck. - You can reinstall at any time without losing configuration.
To stop billing as well, cancel your subscription from your CrossCheck org's Billing page.
Self-hosted GitHub Enterprise
Not yet supported. The GitHub App is hosted by CrossCheck on github.com.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Repo overview shows "GitHub App not installed" (412) | App was uninstalled on GitHub, or repo is outside the App's selected scope. | Reinstall, or add the repo to the selection on GitHub. |
| PRs don't get reviewed | Repo missing from App scope, or repo has no check groups attached. | Add the repo to the App selection on GitHub, or attach at least one check group. |
CrossCheck check stays in_progress forever | Worker died mid-run. | Reviews older than 90 min are auto-failed by the sweeper. Click Re-review to retry. |
| Sticky comment doesn't update on push | Webhook delivery failed. | Check the Recent deliveries tab on the GitHub App page and click Redeliver. |