Accessibility testing in GitHub Actions

Install

Add one workflow file. There is no checkout, no setup-node and no browser install: the scan runs on Accessibility Pro's infrastructure, and the Action is a dependency-free Node script that calls it. The Action is listed on the GitHub Marketplace and its source is MIT licensed.

# .github/workflows/accessibility.yml
name: Accessibility
on: pull_request

permissions:
  pull-requests: write   # post the results comment
  id-token: write        # count free-tier quota against this repo

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: accessibility-pro/action@v2
        with:
          url: ${{ secrets.STAGING_URL }}

The URL must be reachable from the internet, because the scanner loads it the way a visitor's browser would. A preview deployment per pull request works well; store its address as a secret if it is not public.

Permissions

pull-requests: write lets the Action post or update its comment. Without it you get a warning and the results still appear in the job summary. id-token: write lets the Action prove, with a signed GitHub OIDC token, which repository the free-tier quota belongs to, so no other workflow can spend it. Without it the scan still runs and quota is bucketed on the repository name the workflow reports, which nothing verifies.

Pull requests from forks receive a read-only token by design, so the comment is skipped there. That never fails the build.

Inputs

Outputs

With several URLs, counts are summed across pages, and score, scan-id and report-url describe the worst page, the one to open first.

Sample workflows

Gate on conformance, not severity

fail-on: wcag fails the build for any Level A or AA success-criterion failure, whatever severity it carries. Use it when you are working to a compliance deadline such as the European Accessibility Act or ADA.

      - uses: accessibility-pro/action@v2
        with:
          url: https://staging.example.com
          wcag-level: AA
          fail-on: wcag

Scan several pages in one step

Each page is a separate scan against your quota.

      - uses: accessibility-pro/action@v2
        with:
          url: |
            https://staging.example.com/
            https://staging.example.com/pricing
            https://staging.example.com/checkout

Track findings in the Security tab

SARIF fingerprints match the scanner's own baseline keys, so code scanning tracks a finding across runs as fixed or reintroduced. Results appear in the Security tab, not on source lines, because a URL scan has no source file to annotate.

      - uses: accessibility-pro/action@v2
        id: a11y
        with:
          url: https://staging.example.com
          sarif-file: a11y.sarif
          fail-on: none          # let code scanning own the verdict

      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: a11y.sarif
          category: accessibility

Pay down a backlog without a red build every day

No new criticals, and no more than five high-severity findings.

      - uses: accessibility-pro/action@v2
        with:
          url: https://staging.example.com
          thresholds: '{"critical": 0, "high": 5}'

Use the results in later steps

      - uses: accessibility-pro/action@v2
        id: a11y
        with:
          url: https://staging.example.com
          fail-on: none

      - name: Block release below 90
        if: steps.a11y.outputs.score < 90
        run: |
          echo "Score ${{ steps.a11y.outputs.score }}, report ${{ steps.a11y.outputs.report-url }}"
          exit 1

Watch production overnight

A scheduled run has no pull request to comment on, so results go to the job summary and the workflow's failure notification.

on:
  schedule:
    - cron: '0 6 * * *'

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: accessibility-pro/action@v2
        with:
          url: https://www.example.com
          fail-on: wcag

Exit codes

The step exits with 0 when every URL was scanned and cleared the gate, and always when fail-on: none is set and every URL was scanned. It exits with 1, with the reason in the log, in four cases:

• the gate failed: a threshold was crossed on at least one URL, with a link to the worst report;
• one or more URLs could not be scanned at all; results for the others are still in the job summary;
• the result was unrepresentative and fail-on-unrepresentative is true;
• the scan could not run: a rate limit, a rejected token, a blocked URL or a backend error after the retries.

The verdict is computed by the scanner, not by the Action, so the build result and the hosted report always agree. Two kinds of finding appear in the report but never gate a build: markup your code does not own (component-library portals, consent widgets, reCAPTCHA and Turnstile frames) and rules that are not WCAG success criteria, including 4.1.1, which WCAG 2.2 removed. Both are disclosed in the comment.

Free tier and tokens

Without a token, a repository gets 10 scans a day and 10 an hour, so an accidental loop cannot drain the day's allowance in minutes. With an accessibility-pro-token, scans are attributed to your account and draw on your plan's CI allowance, which is separate from interactive scans: 300 a month signed in on the free plan, 1,000 on Developer, 10,000 on Team and 40,000 on Business. See plans and CI allowances.

      - uses: accessibility-pro/action@v2
        with:
          url: ${{ secrets.STAGING_URL }}
          accessibility-pro-token: ${{ secrets.ACCESSIBILITY_PRO_TOKEN }}

The Action prints the remaining allowance on each run and warns at 90%. Copy-as-PR fixes are generated in the hosted report while you are signed in there; the token does not carry into that surface.

When your staging site blocks the scanner

Bot protection, a web application firewall or an IP allow-list can refuse the scan before it sees a page. The Action then fails as unrepresentative instead of passing on an error page. The guide to allowing the scanner through your firewall lists the fixed addresses, the User-Agent token and the per-site request header to allow, with a ready-made Cloudflare rule.

How accurate the gate is

Findings carry their evidence level, from verified by interaction down to a single engine's report, and AI-written text is labelled as such. The scanner's precision and recall on annotated fixtures and a field audit of real websites are published.