CI/CD Accessibility Integration Guide

Integrating accessibility testing into a CI/CD pipeline shifts accessibility
checks left — detecting failures at the point of development rather than
after release. This reduces the cost of fixing issues, prevents regressions,
and creates a consistent baseline that every deployment must meet before
code reaches production.
^[1]

---

Why CI/CD integration matters

Manual and ad-hoc accessibility testing catches issues after they have been
built and deployed. Automated checks in the pipeline catch them before they
reach users. The cost difference is significant — a failure caught in a pull
request review takes minutes to fix; the same failure discovered in a legal
complaint takes months.

---

What CI/CD integration can and cannot catch

Automated pipeline checks can detect:

• Missing alt text, form labels, and accessible names
• Colour contrast failures on solid backgrounds
• Missing landmark regions and heading structure issues
• ARIA attribute errors and invalid role usage
• Duplicate IDs and other structural failures

They cannot replace manual testing for:

• Behavioural keyboard and focus management issues
• Screen reader announcement quality
• Contextual quality judgements on alt text and labels

^[2]

Use CI/CD checks as a regression prevention layer, not as a compliance
certification mechanism.

---

Integration options

Using a11ytest.ai

a11ytest.ai provides a scan API designed for CI/CD integration. A single
POST request triggers a scan against one or more URLs and returns structured
results with pass/fail status, issue counts by severity, and per-page
report URLs. Issues can be automatically pushed to Jira or Azure DevOps
backlogs as part of the same pipeline step.
^[3]

Example Azure DevOps pipeline step:

- script: |
    RESP=$(curl -s -w "\n%{http_code}" -X POST https://a11ytest.ai/api/ci/scan \
      -H "Authorization: Bearer $(A11YTEST_API_KEY)" \
      -H "Content-Type: application/json" \
      -d '{"urls": ["https://your-staging-url.com"]}')
    HTTP_CODE=$(echo "$RESP" | tail -n1)
    if [ "$HTTP_CODE" != "200" ]; then exit 1; fi
  displayName: 'Accessibility scan'

Using axe-core directly

axe-core can be integrated into end-to-end test suites using Playwright
or Cypress:

// Playwright + axe-core
const { checkA11y } = require('axe-playwright')
await checkA11y(page, null, { runOnly: ['wcag2a', 'wcag2aa', 'wcag21aa'] })

---

GitHub Actions example

name: Accessibility

on: [push, pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run accessibility scan
        run: |
          curl -X POST https://a11ytest.ai/api/ci/scan \
            -H "Authorization: Bearer ${{ secrets.A11YTEST_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"urls": ["${{ vars.STAGING_URL }}"]}'

---

Pipeline strategy

On pull requests: Run fast checks against changed pages only. Fail the
PR on critical and serious violations. This keeps developer feedback loops
short.

On merge to main: Run a full scan across all key pages. Push issues
to the backlog. Generate a report for the accessibility audit trail.

On a schedule: Run weekly scans against production to catch regressions
from third-party content, CMS changes, or dependency updates that bypass
the PR process.
^[1]

---

References

1. W3C Web Accessibility Initiative. Integrating Accessibility into Your Development Process. https://www.w3.org/WAI/planning/org-policies/ ↑
2. Deque Systems. The Automated Accessibility Coverage Report. https://www.deque.com/automated-accessibility-coverage-report/ ↑
3. A11YTEST.AI LTD. a11ytest.ai — CI/CD Accessibility Integration. https://a11ytest.ai ↑