Menu
Integrate GitHub Accessibility Scanner. Detects configuration, parses scanner issues, correlates with local scans, and tracks Copilot-assigned fixes.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use for web accessibility work in HTML, JSX, CSS, ARIA, keyboard, forms, contrast, modals, live regions, headings, links, tables, or WCAG review; starts accessibility-lead first and uses tool_search if subagent tools are lazy-loaded.
Developer tools accessibility router for Python, wxPython, desktop accessibility APIs, NVDA add-ons, scanner tooling, CI tooling, and accessibility developer experience.
Document accessibility router for Word, Excel, PowerPoint, PDF, EPUB, Office remediation, PDF remediation, and accessible generated documents.
GitHub workflow accessibility router for PR review, issues, Actions, releases, projects, security alerts, notifications, repository management, and accessible contributor workflows.
Markdown accessibility router for docs, README files, headings, links, tables, alt text, diagrams, generated docs, and publication-ready accessible markdown.
Compute web accessibility scores (0-100, A-F grades) with severity scoring, confidence levels, and remediation tracking across audits.
| name | github-a11y-scanner |
| description | Integrate GitHub Accessibility Scanner. Detects configuration, parses scanner issues, correlates with local scans, and tracks Copilot-assigned fixes. |
The GitHub Accessibility Scanner (github/accessibility-scanner@v2) is an official GitHub Action that:
Current version: v2 (public preview)
To determine whether a repository has the GitHub Accessibility Scanner configured:
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
When a scanner workflow is found, extract its configuration:
| Input | Required | Description |
|---|---|---|
urls | Yes | Newline-delimited list of URLs to scan |
repository | Yes | Repository (owner/name) where issues and PRs are created |
token | Yes | Fine-grained PAT with write access (contents, issues, PRs, metadata) |
cache_key | Yes | Filename for caching results across runs (e.g., cached_results-mysite.json) |
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 | Stringified JSON for complex authentication (Playwright session state) |
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) |
The scanner creates GitHub Issues with a structured format. Agents should parse these fields:
Scanner-created issues can be identified by:
Scanner issues typically contain:
| Section | Content | Agent Use |
|---|---|---|
| Violation title | The axe-core rule that was violated | Map to 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 |
The scanner uses axe-core impact levels that map directly to the agent severity model:
| Scanner Impact | Agent Severity | Score Weight |
|---|---|---|
| Critical | Critical | -15 (both sources) / -10 (single source) |
| Serious | Serious | -7 (high confidence) |
| Moderate | Moderate | -3 (high confidence) |
| Minor | Minor | -1 |
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:
| axe-core Rule ID | WCAG Criterion | Common Description |
|---|---|---|
image-alt | 1.1.1 | Images must have alternate text |
label | 1.3.1 | 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 | 1.3.1 | Heading levels should increase by one |
aria-allowed-attr | 4.1.2 | ARIA attributes must be allowed for element role |
The scanner uses a cache_key to persist results across workflow runs. This enables delta tracking:
| Status | Meaning |
|---|---|
| New | Issue found in current scan but not in cached results |
| Fixed | Issue in cached results but not found in current scan (issue auto-closed) |
| Persistent | Issue found in both current scan and cached results |
When setting up scanner integration, align the cache key with agent conventions:
cached_results-{domain}-{branch}.jsonWhen both the GitHub Accessibility Scanner (CI) and a local axe-core scan (agent) find the same issue:
color-contrast, image-alt)high confidence| Scenario | Interpretation | Action |
|---|---|---|
| Found by scanner AND local scan | High confidence -- confirmed by both | Report as high confidence, full severity weight |
| Found by scanner only | Environment-specific or intermittent | Report as medium confidence, note "CI-only finding" |
| Found by local scan only | New since last CI scan, or local-only condition | Report as medium confidence, note "local-only finding" |
| In scanner cache as "fixed" | Recently remediated | Track in delta section as resolved |
When the scanner assigns issues to GitHub Copilot:
| Stage | GitHub State | How to Detect |
|---|---|---|
| Issue created | Open issue, assigned to Copilot | assignee includes Copilot bot |
| Fix proposed | Open PR linked to issue | PR references issue number, author is Copilot |
| Fix reviewed | PR has review comments | PR review state is CHANGES_REQUESTED or APPROVED |
| Fix merged | PR merged, issue closed | Issue state is closed, linked PR is merged |
| Fix rejected | PR closed without merge | PR state is closed, not merged |
# 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
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"
}
repo:{OWNER}/{REPO} is:issue label:accessibility created:>{YYYY-MM-DD}
Issues from a specific scan run share the same creation timestamp and batch pattern. Filter by:
user:{USERNAME} is:issue label:accessibility sort:created-desc
org:{ORGNAME} is:issue label:accessibility sort:created-desc