github-a11y-scanner

GitHub Accessibility Scanner Integration

What Is the GitHub Accessibility Scanner?

The GitHub Accessibility Scanner (github/accessibility-scanner@v2) is an official GitHub Action that:

• Scans live URLs for accessibility barriers using axe-core in a headless browser
• Creates trackable GitHub Issues for each finding, with affected element, WCAG criterion, and remediation guidance
• Optionally assigns issues to GitHub Copilot for AI-powered fix suggestions and PR creation
• Caches results across runs for delta detection (new, fixed, persistent findings)
• Supports authenticated scanning (login flows, SSO, passkeys via Playwright auth context)
• Optionally captures screenshots and attaches them to filed issues

Current version: v2 (public preview)

Detecting Scanner Presence

To determine whether a repository has the GitHub Accessibility Scanner configured:

Workflow File Detection

Search for workflow files referencing the scanner action:

# Search in .github/workflows/ for the scanner action reference
grep -rl "github/accessibility-scanner" .github/workflows/

Pattern to match in YAML:

- uses: github/accessibility-scanner@v2

Workflow Inputs

When a scanner workflow is found, extract its configuration:

Parsing Scanner-Created Issues

The scanner creates GitHub Issues with a structured format. Agents should parse these fields:

Issue Identification

Scanner-created issues can be identified by:

1. Author: The GitHub Actions bot that runs the workflow
2. Labels: The scanner applies labels to categorize findings (typically accessibility-related labels)
3. Body structure: Issues contain structured sections with violation details

Issue Body Structure

Scanner issues typically contain:

Severity Mapping

The scanner uses axe-core impact levels that map directly to the agent severity model:

axe-core Rule Correlation

The scanner uses axe-core under the hood. Scanner issue titles and violation IDs correspond to axe-core rules already cataloged in help-url-reference. Common scanner-reported rules:

Caching and Delta Detection

The scanner uses a cache_key to persist results across workflow runs. This enables delta tracking:

Cache Key Conventions

When setting up scanner integration, align the cache key with agent conventions:

• Use a descriptive name: cached_results-{domain}-{branch}.json
• Include branch context for branch-specific scanning
• The cache is stored as a GitHub Actions artifact

Correlation with Local Scans

Dual-Source Confidence Boosting

When both the GitHub Accessibility Scanner (CI) and a local axe-core scan (agent) find the same issue:

1. Match by rule ID: Both sources use axe-core rule IDs (e.g., color-contrast, image-alt)
2. Match by URL: Compare the scanned URL from the scanner issue with the local scan target
3. Match by element: Compare CSS selectors or HTML paths for the affected element
4. Boost confidence: Findings confirmed by both sources automatically receive high confidence

Source Comparison Analysis

Copilot Fix Tracking

When the scanner assigns issues to GitHub Copilot:

Fix Lifecycle

Querying Copilot Fix Status

# Find scanner issues assigned to Copilot
repo:{REPO} is:issue is:open assignee:copilot label:accessibility

# Find Copilot PRs from scanner issues
repo:{REPO} is:pr author:copilot-swe-agent label:accessibility

# Find merged scanner fixes
repo:{REPO} is:pr is:merged author:copilot-swe-agent label:accessibility

Structured Output Format

When scanner-bridge normalizes scanner issue data, it produces findings in this format:

{
  "source": "github-a11y-scanner",
  "ruleId": "color-contrast",
  "wcagCriterion": "1.4.3",
  "wcagLevel": "AA",
  "severity": "serious",
  "confidence": "high",
  "url": "https://example.com/login",
  "element": "button.submit-btn",
  "description": "Element has insufficient color contrast ratio of 3.2:1 (expected 4.5:1)",
  "remediation": "Change the text color or background to achieve at least 4.5:1 contrast ratio",
  "githubIssue": {
    "number": 42,
    "url": "https://github.com/owner/repo/issues/42",
    "state": "open",
    "copilotAssigned": true,
    "fixPR": null
  },
  "screenshot": "https://github.com/owner/repo/blob/gh-cache/screenshots/login-contrast.png"
}

Search Patterns for Scanner Issues

By Repository

repo:{OWNER}/{REPO} is:issue label:accessibility created:>{YYYY-MM-DD}

By Scan Run

Issues from a specific scan run share the same creation timestamp and batch pattern. Filter by:

• Creation date matching the workflow run date
• Common label set applied by the scanner

Cross-Repository Scanner Discovery

user:{USERNAME} is:issue label:accessibility sort:created-desc
org:{ORGNAME} is:issue label:accessibility sort:created-desc