/kb-github-a11y-scanner

name: kb-github-a11y-scanner
description: Reference data, not a reviewer. Integrate GitHub Accessibility Scanner. Detects configuration, parses scanner issues, correlates with local scans, and tracks Copilot-assigned fixes.
license: MIT
disable-model-invocation: true
user-invocable: false
metadata:
  tier: reference
  domain: cross-cutting
  output: none
  effort: low
  title: Github A11y Scanner

GitHub Accessibility Scanner Integration

What Is the GitHub Accessibility Scanner?

The [GitHub Accessibility Scanner](https://github.com/github/accessibility-scanner) (`github/accessibility-scanner@v3`) is an official GitHub Action that:

• Scans live URLs for accessibility barriers in a headless Playwright browser (axe-core by default; `accesslint` and plugins are optional)
• 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:** v3 (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@v3

Workflow Inputs

When a scanner workflow is found, extract its configuration:

| Input | Required | Description | |-------|----------|-------------| | `urls` | Yes, unless `url_configs` is set | Newline-delimited list of URLs to scan | | `url_configs` | No | JSON array of per-URL configs (`url`, optional `excludeSelectors` and `waitForSelectors`); takes precedence over `urls` | | `repository` | Yes | Repository (owner/name) where issues and PRs are created | | `token` | Yes | Fine-grained PAT: `actions`, `contents`, `issues` and `pull-requests` write, `metadata` read. `GITHUB_TOKEN` does not work | | `cache_key` | Yes | Key for caching results across runs; characters `A-Za-z0-9._/-` | | `login_url` | No | Login page URL for authenticated scanning | | `username` | No | Username for authentication | | `password` | No | Password for authentication (via repository secret) | | `auth_context` | No | JSON with username, password, cookies and/or localStorage; overrides `login_url`, `username`, `password` | | `skip_copilot_assignment` | No | Set `true` to skip assigning issues to Copilot | | `include_screenshots` | No | Set `true` to capture screenshots (stored on `gh-cache` branch) | | `group_by` | No | `finding` (default), `rule` or `rule+url`; decides how many issues are filed | | `scans` | No | Scanners to run: `axe` (default), `accesslint`, or plugin names | | `dry_run` | No | Log what would be filed without touching issues or the cache |

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:

| Section | Content | Agent Use | |---------|---------|-----------| | Violation title | The axe-core rule that was violated | Map to `kb-help-url-reference` for remediation docs | | WCAG criterion | The specific WCAG success criterion | Used for severity scoring and compliance mapping | | Affected element | CSS selector or HTML snippet of the failing element | Used by `scanner-bridge` to map to source code | | Impact level | Critical, Serious, Moderate, or Minor | Direct mapping to agent severity model | | Remediation guidance | How to fix the issue | Enriched by agent specialists with framework-specific fixes | | URL | The page URL where the issue was found | Used for cross-referencing with local axe-core scans | | Screenshot link | Link to screenshot on `gh-cache` branch (if enabled) | Included in audit reports |

Severity Mapping

The scanner uses axe-core impact levels that map directly to the agent severity model. Weights are the ones in `skills/a11y-core/scripts/merge-findings.mjs`, multiplied by confidence (high 1, medium 0.7, low 0.4):

| Scanner Impact | Agent Severity | Score Weight | |---------------|---------------|-------------| | Critical | critical | 10 | | Serious | serious | 5 | | Moderate | moderate | 2 | | Minor | minor | 1 |

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 `kb-help-url-reference`. Common scanner-reported rules:

| axe-core Rule ID | WCAG Criterion | Common Description | |-------------------|----------------|-------------------| | `image-alt` | 1.1.1 | Images must have alternate text | | `label` | 4.1.2 | Form elements must have labels | | `color-contrast` | 1.4.3 | Elements must have sufficient color contrast | | `link-name` | 2.4.4 | Links must have discernible text | | `html-has-lang` | 3.1.1 | `<html>` element must have a lang attribute | | `button-name` | 4.1.2 | Buttons must have discernible text | | `document-title` | 2.4.2 | Documents must have `<title>` element | | `bypass` | 2.4.1 | Page must have means to bypass repeated blocks | | `heading-order` | none (best-practice; relates to 1.3.1) | Heading levels should increase by one | | `aria-allowed-attr` | 4.1.2 | ARIA attributes must be allowed for element role |