GitHub App Docs — ADAGuard

GitHub App

Accessibility scanning on every pull request — automatic, zero config, works with any URL.

Overview

The ADAGuard GitHub App scans any URL on every pull request and posts the accessibility score and issues as a PR comment with a GitHub Check Run. It auto-detects the preview deployment URL from the PR — or you can point it at any URL you want via a config file in your repo.

Zero config

Install once, every PR gets scanned. No setup required.

Any URL

Scan the auto-detected preview or set a custom URL.

GitHub Check Run

Pass/fail status directly in the PR — block merges on critical issues.

Install on GitHub Manage Integration

Installation

1
Install the GitHub App
Click "Install on GitHub" above. Select the repositories you want to scan. Free tier covers 1 repository.
2
Open a pull request
That's it. The app listens for deployment events on your PRs. When your CI pushes a deployment, ADAGuard scans it automatically.
3
View the results
An accessibility score, issue list, and fix links appear as a PR comment. A GitHub Check Run shows pass or fail.
4
Optional: add .adaguard.yml
Drop a .adaguard.yml in your repo root to customise the URL, set a score threshold, or ignore specific rules.

How It Works

When you open or update a PR, GitHub sends a deployment_status event when your CI finishes deploying. ADAGuard receives the event, detects the URL, and kicks off a scan. Results are posted back to GitHub as a PR comment and a Check Run within seconds of the scan finishing.

Push to branch → CI deploys preview → GitHub fires deployment_status event → ADAGuard detects URL → Runs accessibility scan → Posts PR comment + Check Run

If no deployment event fires (e.g. your repo doesn't use a preview platform), you can still set a in .adaguard.yml and the app will scan it on every PR.

.adaguard.yml

Drop this file in your repo root to customise behaviour. All fields are optional — the app works with zero configuration.

[ .ADAGUARD.YML ]

# .adaguard.yml

# Set a custom URL to scan on every PR.
# If omitted, the app scans the auto-detected preview deployment URL.
# url: https://your-site.com

# Block merge when score drops below this threshold (paid plans).
fail_on_score_below: 70

# Suppress specific rule types (use the "type" field from scan results).
ignore_rules:
  - broken-links-redirect

# Vercel bypass token for protected preview deployments.
# Get it from: Vercel Dashboard → Project → Settings → Deployment Protection
# vercel_bypass_token: your-secret-here

# Max pages to scan per PR (default 1, up to 3 on paid plans).
max_pages: 1

Field	Type	Default	Description
url	string	auto	Custom URL to scan. Overrides the auto-detected preview URL.
fail_on_score_below	int 0–100	null	Fail the Check Run when score drops below this value. Paid plans only.
ignore_rules	string[]	[]	Issue type strings to suppress from results.
vercel_bypass_token	string	null	Vercel Deployment Protection bypass secret.
max_pages	int 1–3	1	Pages to scan per PR. Capped to plan limit.

Custom URL

By default the app scans the preview deployment URL detected from the GitHub deployment event. To scan a different URL — your staging environment, production site, or any URL — set the url field:

[ .ADAGUARD.YML ]

# Always scan this URL on every PR, regardless of deployment events
url: https://staging.your-site.com

This is useful when your repo doesn't use a preview platform, when you want to scan a shared staging environment, or when you want to test production instead of the PR preview.

Vercel Bypass Token

If your Vercel previews use Deployment Protection, the app will hit the login wall instead of your app. Add your bypass token to let ADAGuard through.

[ .ADAGUARD.YML ]

vercel_bypass_token: your-bypass-secret-here

Where to get it: Vercel Dashboard → your project → Settings → Deployment Protection → copy the bypass secret.

Keep it secret. Do not commit it in plain text — use a GitHub secret and reference it, or rely on the dashboard integration in Settings → Integrations which stores it encrypted.

Plan Limits

Feature	Free	Starter	Professional+
Repositories	1	2	Unlimited
Issues shown per PR	Top 5	All	All
Fix guide links	✅	✅	✅
Regression tracking	—	✅	✅
Block merge on critical	—	—	Business+
Max pages per scan	1	1	Up to 3

View full pricing →

Auto-detected Platforms

When no url is set in .adaguard.yml, the app detects the preview URL from the GitHub deployment event. These platforms send deployment events that ADAGuard can read automatically:

VercelNetlifyRailwayFly.ioCloudflare PagesAWS AmplifyHerokuRenderSurge.sh

Don't use any of these? No problem — set a in .adaguard.yml and it works with any deployment setup.

Troubleshooting

My PR was never scanned — no comment, no Check Run

•Confirm the app is installed on this repository: GitHub → Settings → Integrations → ADAGuard.
•Check your repo count against your plan limit (Free = 1 repo). The app posts a one-time limit notice when exceeded.
•If your platform doesn't send deployment events (see Auto-detected Platforms above), set url: in .adaguard.yml so the app always has something to scan.
•Closed or merged PRs are never scanned — deployment events that arrive after merge are ignored.

The comment says "Preview URL Not Found"

•Your CI may not be emitting a deployment_status event. Paste the preview URL into the PR description (e.g. "Preview: https://your-app.fly.dev") and push again.
•Or set a permanent scan URL: dashboard Settings → Integrations → your repo → Scan URL override, or url: in .adaguard.yml.

I got a very low score and the report mentions a login page

•ADAGuard hit an authentication wall instead of your app. For Vercel Deployment Protection, add your bypass token (see Vercel Bypass Token above).
•If your app itself requires login, point the scan at a public page or your production URL instead.

The wrong deployment was scanned (e.g. my API instead of the frontend)

•When a PR triggers multiple deployments, ADAGuard picks the most likely frontend URL. The "Tested" row in the PR comment shows which one.
•To pin it, set scan_deployment_pattern: "frontend-*.vercel.app" (glob) or a fixed url: in .adaguard.yml.

The same PR has a stale comment after I pushed a fix

•ADAGuard updates its existing comment in place on every push. If it looks stale, the scan may have timed out (2-minute limit) — check the Check Run status, then push again to retry.

Still stuck? Email [email protected] with your repo name and PR link.

FAQ

Does it work without a .adaguard.yml file?

Yes. Zero config needed. The app auto-detects the preview deployment URL from the PR and scans it. Add .adaguard.yml only when you want to customise the URL, score threshold, or ignored rules.

Can it scan a custom URL instead of the preview deployment?

Yes. Set url: https://your-site.com in .adaguard.yml and the app scans that URL on every PR — useful for staging environments, production sites, or repos that don't use a preview platform.

My Vercel previews are protected — can ADAGuard still scan them?

Yes. Add your bypass secret to .adaguard.yml under vercel_bypass_token. Get the secret from: Vercel Dashboard → Project → Settings → Deployment Protection.

Will it scan every push or just PRs?

Only pull requests. The app listens for deployment_status events tied to a PR and ignores main-branch deploys to avoid unnecessary scans.

How do I silence specific rules?

Use the ignore_rules field in .adaguard.yml with the issue type string (e.g. broken-links-redirect). Issue type values are visible in the full scan report.

What does "regression tracking" mean?

On Starter plans and above, ADAGuard compares the score to the previous PR scan. If the score dropped or improved by more than 5 points, it shows a warning or improvement note in the PR comment.