Your Pipeline Has Linting and Security Scans. Why Not Accessibility?

Your CI runs ESLint. It runs your test suite. Maybe Semgrep or Snyk for security. If any of those fail, the PR doesn't merge. But accessibility? On most teams it's still a manual audit someone schedules after launch, if it happens at all — pipeline-grade tooling has lagged the rest of the quality stack.

That's why I built a public API for AccessHawk, shipped in March 2026. Submit a URL, get JSON back with the violations, what's broken, and how to fix it. Fail the build on critical issues. Post a summary as a PR comment. It's the same scan you'd run in the browser (Playwright, Lighthouse, and AI analysis), just triggered over HTTP instead of a dashboard.

Why accessibility testing belongs in CI/CD#

Most teams wouldn't ship without unit tests. But accessibility still gets punted to a manual audit three weeks after launch. A missing alt attribute or a broken focus order that slips into production can take 10x more effort to fix than one caught during a pull request review.

That's changing. WCAG enforcement is showing up in legal settlements and government procurement requirements. Teams can't afford to treat accessibility as a post-launch audit anymore. Shift-left means catching violations before they reach staging, let alone production.

The cost of late detection#

• Development phase: a developer fixes a contrast issue in 5 minutes
• QA phase: a tester files a bug, a developer context-switches back to fix it. 30 minutes.
• Post-launch: legal review, remediation planning, regression testing. Days to weeks.
• Legal action: ADA lawsuits and demand letters are increasing every year, and settlements aren't cheap

Automated accessibility checks in your pipeline pay for themselves fast.

What AccessHawk actually scans for#

Most accessibility tools do one thing. Lighthouse checks rules, or an AI reads a screenshot. AccessHawk runs all three and cross-references the results.

1. Browser automation with Playwright#

Every scan launches a real Chromium browser that loads your page exactly as a user would see it. AccessHawk captures full-page screenshots for visual analysis, the accessibility tree (the same structure screen readers use to navigate your page), and raw HTML for structural analysis: heading hierarchy, landmark regions, form labels.

2. Lighthouse accessibility audits#

Google Lighthouse runs its full accessibility audit suite, checking dozens of WCAG criteria with deterministic rules. This catches clear-cut violations:

• Missing alt text on images
• Insufficient color contrast ratios
• Missing form labels and ARIA attributes
• Incorrect heading hierarchy
• Keyboard navigation issues

3. AI-powered contextual analysis#

An LLM (Claude, GPT, or Gemini, your choice) analyzes the combined context from the screenshot, accessibility tree, HTML, and Lighthouse results. The AI catches nuanced issues that rule-based tools miss:

• Decorative images incorrectly marked as informative
• Ambiguous link text ("click here", "read more") without surrounding context
• Logical reading order issues that pass automated checks but confuse screen readers
• ARIA misuse where attributes are present but semantically wrong

Results include WCAG success criteria references, severity levels, and specific recommendations for fixing each issue.

How the API works#

Four steps:

1. Authenticate with an API key from your account settings
2. Submit a scan with the target URL and configuration options
3. Get results by polling the status endpoint, or provide a webhook URL and get notified when it's done
4. Process the response and parse the structured JSON for your pipeline logic

The API returns issues categorized by WCAG level (A, AA, AAA), severity (critical, high, medium, low), and specific success criteria (e.g., 1.4.3 Contrast). Each issue includes the element location, a description of the impact, and a recommendation for fixing it.

Pipeline integration patterns#

Here's where accessibility scanning fits in a typical CI/CD workflow. The examples below use GitHub Actions and GitLab CI, but the pattern is the same on any platform.

GitHub Actions#

name: Accessibility Check
on:
  pull_request:
    branches: [main]

jobs:
  a11y-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Wait for preview deployment
        run: ./scripts/wait-for-deploy.sh

      - name: Run AccessHawk scan
        env:
          ACCESSHAWK_API_KEY: ${{ secrets.ACCESSHAWK_API_KEY }}
        run: |
          ./scripts/accesshawk-scan.sh "$PREVIEW_URL"

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: accessibility-report
          path: ./a11y-results.json

GitLab CI#

accessibility_scan:
  stage: test
  needs: [deploy_staging]
  script:
    - ./scripts/accesshawk-scan.sh "$STAGING_URL"
  artifacts:
    paths:
      - a11y-results.json
    when: always
  rules:
    - if: $CI_MERGE_REQUEST_ID

General pattern#

Regardless of your CI platform, the integration follows the same steps:

1. Deploy to a preview or staging environment
2. Run the AccessHawk scan against that URL
3. Parse the JSON results
4. Apply your threshold rules (e.g., fail on critical/high issues)
5. Post a summary as a PR comment or build annotation
6. Archive the full report as a build artifact

Working with scan results#

The API returns structured JSON with each issue containing the specific WCAG success criterion violated, the level (A, AA, or AAA), severity, the element or selector involved, what's wrong and how it affects users, and a recommendation for fixing it.

That structure is easy to work with in a script:

// Fail the build on critical or high-severity issues
const results = JSON.parse(fs.readFileSync('a11y-results.json', 'utf-8'))
const blocking = results.issues.filter(
  (issue) => issue.severity === 'critical' || issue.severity === 'high',
)

if (blocking.length > 0) {
  console.error(`Found ${blocking.length} blocking accessibility issues:`)
  blocking.forEach((issue) => {
    console.error(
      `  [${issue.severity}] ${issue.criteria}: ${issue.description}`,
    )
  })
  process.exit(1)
}

Getting started#

API access is available on the Hobby, Pro, and Team plans, each with its own monthly scan quota. The free tier is great for one-off scans in the browser, but it doesn't include API access.

1. Create an account at accesshawk.ai/signup if you haven't already
2. Generate an API key from your settings page for CI/CD use
3. Review the API docs. The API documentation has everything: endpoints, authentication, request/response schemas, and rate limits
4. Write your integration script using the patterns above as a starting point
5. Add your API key as a CI secret — store it as ACCESSHAWK_API_KEY in your CI platform's secrets

Best practices#

Scan staging before production#

Run your first scan against a preview or staging deployment. Catch issues before real users are affected. Scanning production is still a good idea (it's the only way to confirm the real environment matches), but staging should always come first in the pipeline.

Make it a required PR check#

Make accessibility scans a required check on pull requests. This prevents regressions from being merged and gives developers immediate feedback while the code is fresh in their minds.

Set severity thresholds#

Not every accessibility issue needs to block a deployment. A practical approach:

• Critical and high issues: block the merge/deploy
• Medium issues: warn in the PR comment but don't block
• Low issues: track for future sprints

Combine with manual audits#

Automated scanning won't catch everything. A modal that traps focus in a weird way, a custom drag-and-drop interaction, a multi-step form with dynamic validation. Those still need a human. Use the API for continuous checks and schedule manual audits for the complex stuff.

Monitor trends over time#

Track your accessibility score across deployments. A gradually increasing issue count signals tech debt accumulating. Address it before it snowballs.

Conclusion#

Accessibility testing in CI/CD is a quality practice, same as linting or security scanning. The earlier you catch a missing label or a broken focus order, the less it costs to fix.

I built AccessHawk because the existing tools either couldn't catch the nuanced issues or couldn't integrate into the workflows where they'd actually get used. The API closes that gap. Same Playwright + Lighthouse + AI scan, now available wherever your code ships.

If your team is shipping without automated accessibility checks, this is a good place to start. One API call in your pipeline catches what manual audits miss between quarterly reviews.