Detect accessibility regressions between pull requests without punishing existing debt.

Unlike standard axe CI integrations that pass/fail absolutely, WCAG_PR_Checker compares accessibility health over time. It blocks a PR only if it makes things worse so teams with legacy debt can mitigate new issues without first fixing everything.

View more information on the website.

1. Base vs PR: The action compares the base branch (e.g. main) to the PR branch — either by building both and serving static files, or by scanning live deployment URLs.
2. Runs axe-core on both via Playwright.
3. Diffs the results — new violations are flagged, resolved violations are celebrated.
4. Posts a structured comment to the PR and optionally fails the check.

Add this to .github/workflows/a11y.yml in any repository:

name: Accessibility Regression Check

on:
  pull_request:

jobs:
  a11y:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Run accessibility check
        uses: zachkklein/WCAG_PR_Checker@v2
        with:
          APP_DIR: '.'
          BUILD_DIR: 'public'
          URLS: '/'
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

1. Set APP_DIR to the location of your projects root directory.
2. Set URLS to contain the routes on your website you wish to check for accessibility issues. Separate routes with a comma (e.g., running the workflow on / and '/contact' would look like `URLS: '/,/contact').

1. Ensure that you have granted write access by setting the permissions section above to:

    permissions:
      contents: write   # required for git-auto-commit push
      pull-requests: write

2. In the GitHub repository that you integrate this workflow into, set the OPENROUTER_API_KEY by navigating to Settings then Environemnt Variables then Actions and add the key as a Repository Secret.

When regressions are found, the action posts a comment like this:

Accessibility Check — Regressions Found

|                  | Baseline | This PR | Delta  |
|------------------|----------|---------|--------|
| Total violations | 12       | 14      | +2     |
| 🔴 Critical       | 0        | 1       | +1 ⬆️  |
| 🟠 Serious        | 3        | 4       | +1 ⬆️  |

New Violations (2)
| Impact       | Rule            | WCAG        | Page  | Selector    | Docs |
|--------------|-----------------|-------------|-------|-------------|------|
| 🔴 critical  | color-contrast  | WCAG 2.1 AA | /     | #submit-btn | docs |

When neither BASE_URL nor PR_URL is set, the action checks out both branches, builds each, serves the static output with npx serve, and scans localhost. This only works when your app produces a static export (e.g. a folder of HTML/JS/CSS).

One way to verify your build folder is to run a build in your repository (i.e. with npm run build when using Next.js, and copy the file path to index.html).

When both BASE_URL and PR_URL are set, the action skips checkout, install, build, and serve. It only installs its own dependencies and Playwright, then scans the two URLs you provide. Use this for:

• Next.js (or any stack) with PR preview deployments (e.g. Vercel, Netlify).
• Any app where the base and PR are already deployed and you have two URLs to compare.

Vercel exposes the PR preview URL in the workflow; you can pass your production or main-preview URL as BASE_URL and the PR deployment as PR_URL.

- uses: zachkklein/WCAG_PR_Checker@main
  with:
    APP_DIR: '.'
    BUILD_DIR: 'dist'
    URLS: '/,/about'

- uses: zachkklein/WCAG_PR_Checker@main
  with:
    APP_DIR: 'frontend'
    BUILD_DIR: '.next/server/app'
    URLS: '/,/dashboard'

Use deployment URLs instead of building locally. No BUILD_DIR or build step — the action only scans the given URLs.

- uses: zachkklein/WCAG_PR_Checker@main
  with:
    BASE_URL: 'https://your-app.vercel.app'      # production or main preview
    PR_URL: ${{ steps.deploy.outputs.url }}      # or env from Vercel GitHub Action
    URLS: '/,/about,/projects'

If you use the Vercel GitHub Action or similar, the PR preview URL is often available as an output or env var — pass that into PR_URL.

- uses: zachkklein/WCAG_PR_Checker@main
  with:
    FAIL_ON_REGRESSION: 'false'
    URLS: '/,/about,/contact'

- uses: zachkklein/WCAG_PR_Checker@main
  with:
    IMPACT_LEVEL: 'serious'
    URLS: '/'

a11y-diff-action/
├── action.yml          # Action definition and inputs
├── package.json        # Self-contained dependencies
└── src/
    ├── scan.js         # Playwright + axe-core scanner
    ├── diff.js         # Violation diffing logic
    ├── comment.js      # PR comment formatting and posting
    └── auto-fix.js     # Optional: AI fixes and commits back to PR (needs OPENROUTER_API_KEY, contents: write)

• Zach Klein
• Andrew Bacigalupi
• Thee Thakong
• Alex Vu
• William Goldman
• Ethan Li

MIT License -- See LICENSE.txt