Docs — SEOCode

Getting Started

Up and running
in 30 seconds.

SEOCode is a GitHub App. No CI config, no tokens, no YAML. Install it and every pull request is automatically reviewed.

01

Install the GitHub App

Go to github.com/apps/seocode, click Install, and choose which repositories to grant access to. You can select all repos or specific ones.

02

Open a pull request

SEOCode triggers on pull_request events — specifically opened, synchronize, and reopened. No manual trigger needed.

03

Review the SEO report

A comment appears on your PR listing every issue found, the exact fix to apply, and a link to the relevant spec. The PR status check shows pass or fail depending on whether any critical issues were found.

How it works

What gets scanned.

SEOCode reads every supported file in your repository at the commit SHA of the PR head. It never stores your code.

File types

.html .jsx .tsx .vue .svelte

When it runs

On every PR open, push, and reopen. Automatically — no manual trigger.

Data handling

File contents are parsed in-memory and discarded immediately. Nothing is stored.

Framework shells (React, Vue, Svelte entry files with mount points) and utility files are automatically detected and skipped for rules that don't apply — no false positives on component-only files.

PR Comment

Reading the report.

Every issue is categorised by severity. Fix critical issues before merging — warnings and info are advisory.

Critical

Issues that directly harm search indexing or ranking. Missing title tag, accidental noindex, missing H1. The PR status check is set to failure when any critical issue is found.

Warning

Issues that degrade SEO quality but don't break indexing. Missing Open Graph tags, broken heading hierarchy, title too long. Status check remains passing.

Info

Best-practice recommendations. Missing canonical URL, no structured data, images missing lazy loading. Advisory only — no status check impact.

GitHub Permissions

Minimum access,
nothing more.

SEOCode requests only the permissions it needs to do its job. You can review and revoke these at any time from your GitHub settings.

Contents: Read

Allows SEOCode to read repository files at a specific commit SHA. Used to fetch HTML, JSX, TSX, Vue, and Svelte files for analysis. File contents are processed in-memory and never stored.

Pull requests: Read & Write

Allows SEOCode to post and update the SEO review comment on your pull request. The Write permission is needed only to create and edit that single comment — SEOCode does not merge, close, or modify your PRs in any other way.

Commit statuses: Read & Write

Allows SEOCode to post a pass or fail status check on the PR commit. This is what blocks merging when critical SEO issues are found, and what shows the green checkmark when everything passes.

Revoking access

Go to GitHub → Settings → Applications → Installed GitHub Apps, find SEOCode, and click Configure. You can remove individual repositories or uninstall the app entirely.

PR Status Check

What the status
check looks like.

Every reviewed PR gets a commit status under the context seocode/review. You can require this check to pass before merging via your branch protection rules.

Failure

One or more Critical issues were found. The check blocks merging if your branch protection rules require it. The PR comment lists the exact issues and fixes.

Success

No critical issues found. Warnings and info items may still appear in the PR comment but they do not affect the status check outcome.

Enforcing the check

To block merging on SEO failures: go to your repo → Settings → Branches → Branch protection rules → enable Require status checks to pass → search for and add seocode/review.

Plans & Limits

What each plan
gets you.

Plans are managed through GitHub Marketplace. Upgrades and downgrades take effect immediately — no manual action needed on your end.

Plan	Price	Rules	Repos	Private repos	Support
Free	$0	10 core rules	1 public repo	—	—
Pro	$29/mo	All rules	Up to 5	✓	Email
Team	$49/mo	All rules	Unlimited	✓	Priority
Agency	$149/mo	All rules	Unlimited orgs	✓	Dedicated

Manage your plan at github.com/marketplace/seocode. Billing is handled entirely by GitHub — no separate payment account needed.

Uninstalling

Removing SEOCode.

You can restrict access to specific repositories or remove SEOCode entirely at any time. No data is retained after uninstall.

01

Remove from specific repos

Go to GitHub → Settings → Applications → Installed GitHub Apps → SEOCode → Configure. Under Repository access, remove the specific repositories you no longer want reviewed.

02

Uninstall entirely

On the same configuration page, scroll to the bottom and click Uninstall. This removes SEOCode from all repositories and revokes all GitHub permissions immediately.

03

Cancel your subscription

If you're on a paid plan, cancel separately at github.com/marketplace/seocode. Uninstalling the app does not automatically cancel billing.

Configuration

Per-repo config.

Fine-tune which rules run, adjust severity levels, or ignore specific files — all from a config file in your repo root.

Coming Soon

Drop a .seocode.json file in your repo root to override rule severity, disable specific rules, or exclude paths. This feature is currently in development and will ship as part of the Team and Agency plan.

Help

Troubleshooting.

Common issues and how to fix them.

SEOCode didn't comment on my PR

Check these in order:

→ The app is installed on that specific repository — go to GitHub → Settings → Applications → Installed GitHub Apps → SEOCode → Configure and confirm the repo is listed.
→ The PR touches at least one supported file type: .html, .jsx, .tsx, .vue, or .svelte. PRs that only change CSS, JSON, or markdown files won't trigger a review.
→ You're on the Free plan and the repository is private. Free plan only covers public repositories. Upgrade to Pro or higher to enable private repo reviews.
→ The webhook delivery succeeded — check GitHub → Settings → Applications → Installed GitHub Apps → SEOCode → Advanced → Recent Deliveries for any failed deliveries.

The PR status check is stuck as "pending"

This usually means the webhook was delivered but the worker timed out. Check Recent Deliveries (see above) — a 504 or no response indicates a timeout. If it persists, contact support with your repository name and PR number.

SEOCode flagged something that isn't an SEO issue

Rules are heuristics — they can produce false positives in some cases (e.g. dynamically rendered titles, intentional noindex on staging routes). Per-repo configuration to suppress specific rules or paths is coming soon. In the meantime, let us know — your feedback directly improves rule accuracy.

I need to re-run the check on an existing PR

Push a new commit to the PR branch. SEOCode triggers on every push and pull_request event — there is no manual re-run button today, but pushing an empty commit (git commit --allow-empty -m "retrigger") will start a fresh review.