How to Check for Accessibility Regressions on a PR in GitHub Actions

Running axe on the pull_request event turns new accessibility violations into a required check that blocks the merge.

Trigger an axe scan on pull_request, run it against the PR build, and let the non-zero exit fail the required status check so regressions cannot merge.

Steps

• Trigger the workflow on the pull_request event.
• Build the PR branch and serve it.
• Run axe; make the job a required status check in branch protection.

Workflow

on:
  pull_request:
jobs:
  a11y-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci && npm run build
      - run: npx serve -l 3000 dist & npx wait-on http://localhost:3000
      - run: npx @axe-core/cli http://localhost:3000 --exit

Gotchas

• Mark the job required in branch protection, or a failing scan will not actually block the merge.
• To gate only on new issues, compare against a baseline of known violations from the target branch.

Related guides