GitHub App
The AEOrank GitHub App scores your site’s AI visibility on every pull request — zero YAML, zero config, one-click install.
Install
Section titled “Install”- Go to github.com/apps/aeorank
- Click Install
- Choose your account and select repositories
- Done — AEOrank now runs on every PR
How it works
Section titled “How it works”When you open or update a pull request, AEOrank automatically:
- Detects your site URL from your repo (see URL detection below)
- Scans your site across 36 AI visibility criteria
- Posts a Check Run on the commit with your score and grade
- Posts a PR comment with a full dimension breakdown and recommendations
The Check Run shows ✅ green (score ≥ 70), grey neutral (40–69), or ❌ red (below 40).
The Check fails if GPTBot (or ClaudeBot, PerplexityBot, Google-Extended) is disallowed in robots.txt, even when the overall score is high. The summary names which bot is blocked. A missing robots.txt is unknown, not a failure.
URL detection
Section titled “URL detection”AEOrank auto-detects your site URL by checking these files in order:
| Priority | File | Format |
|---|---|---|
| 1 | .aeorank | JSON: {"url": "https://your-site.com"} |
| 2 | aeorank.config.js | JS: siteUrl: "https://your-site.com" |
| 3 | CNAME | Plain text: your-site.com |
| 4 | package.json | JSON: "homepage": "https://your-site.com" |
The simplest option: add a .aeorank file to your repo root:
{"url": "https://your-site.com"}If no URL is found, AEOrank posts a neutral Check Run with setup instructions.
What you get
Section titled “What you get”Check Run on every commit
Section titled “Check Run on every commit”The Check Run appears in your PR’s checks tab with:
- AEO Score (0–100) with letter grade (A+ through F)
- Pass/neutral/fail conclusion based on score and crawler blocks
- Crawler table first (allow / block / unknown), then the 36-dimension table
PR comment
Section titled “PR comment”A comment is posted (or updated) on the PR with the full score breakdown. The comment uses a hidden marker (<!-- aeorank-score -->) so re-pushes update the existing comment instead of creating new ones.
Rate limits
Section titled “Rate limits”| Plan | Scans per day |
|---|---|
| Free | 10 per repo |
Scans are counted per installation per day. If you hit the limit, AEOrank posts a neutral Check Run letting you know.
Permissions
Section titled “Permissions”The App requests these permissions:
| Permission | Access | Why |
|---|---|---|
| Checks | Read & write | Post Check Runs on commits |
| Contents | Read-only | Read .aeorank, CNAME, package.json for URL detection |
| Pull requests | Read & write | Post and update PR comments |
| Metadata | Read-only | Required by GitHub for all Apps |
The App subscribes to pull_request and push events.
GitHub App vs GitHub Action
Section titled “GitHub App vs GitHub Action”Both post the same Check Run and PR comment. Choose based on your preference:
| GitHub App | GitHub Action | |
|---|---|---|
| Setup | One-click install | Add YAML workflow file |
| Config | Zero — auto-detects URL | Set url input in workflow |
| Runs on | AEOrank servers | GitHub Actions runners (your minutes) |
| Control | Automatic on every PR | Full control via workflow triggers |
| Crawler block | ✅ Fails the Check if GPTBot (or peer) is disallowed | ✅ fail-on-crawler-block |
fail-below | Not yet (coming soon) | ✅ Set minimum score threshold |
The App does fail the PR when a gated crawler is blocked. It does not support fail-below yet — do not treat the App as a score-threshold merge gate.
Recommendation: Start with the GitHub App for zero friction and crawler-block protection. Switch to the Action if you need fail-below thresholds or custom workflow triggers.
Troubleshooting
Section titled “Troubleshooting””No Site URL Configured” Check Run
Section titled “”No Site URL Configured” Check Run”AEOrank couldn’t detect your site URL. Add a .aeorank file to your repo root:
{"url": "https://your-site.com"}No Check Run appears
Section titled “No Check Run appears”- Verify the App is installed: github.com/settings/installations
- Check that your repo is in the App’s selected repositories
- Push a new commit to the PR to trigger a fresh webhook
Score seems wrong
Section titled “Score seems wrong”AEOrank scans the URL found in your config. Make sure it points to your live, publicly accessible site — not localhost or a staging URL.
Privacy
Section titled “Privacy”The App reads only the files needed for URL detection (.aeorank, CNAME, package.json, aeorank.config.js). It does not access your source code, commits, issues, or any other repository content. See our privacy policy.