github-a11y-scanner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Accessibility Scanner Integration

GitHub Accessibility Scanner 集成

What Is the GitHub Accessibility Scanner?

什么是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)

GitHub Accessibility Scanner（

github/accessibility-scanner@v2

）是GitHub官方推出的Action，具备以下功能：

在无头浏览器中使用axe-core扫描在线URL的可访问性障碍
为每一项发现的问题创建可跟踪的GitHub Issue，包含受影响元素、WCAG标准条款和修复指导
可选择将Issue分配给GitHub Copilot，获取AI生成的修复建议并自动创建PR
跨运行缓存结果，实现差异检测（新增、已修复、持续存在的问题）
支持身份认证扫描（通过Playwright认证上下文实现登录流程、SSO、通行密钥验证）
可选择捕获截图并附加到提交的Issue中

当前版本： v2（公开预览版）

Detecting Scanner Presence

检测扫描器部署情况

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

要判断代码仓库是否配置了GitHub Accessibility Scanner，可以通过以下方式：

Workflow File Detection

工作流文件检测

Search for workflow files referencing the scanner action:

bash

undefined

在工作流文件中搜索对扫描器Action的引用：

bash

undefined

Search in .github/workflows/ for the scanner action reference

grep -rl "github/accessibility-scanner" .github/workflows/


**Pattern to match in YAML:**
```yaml
- uses: github/accessibility-scanner@v2

grep -rl "github/accessibility-scanner" .github/workflows/


**YAML中的匹配模式：**
```yaml
- uses: github/accessibility-scanner@v2

Workflow Inputs

工作流输入参数

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)

找到扫描器工作流后，提取其配置信息：

输入参数	必填	描述
`urls`	是	待扫描的URL列表，用换行分隔
`repository`	是	创建Issue和PR的仓库（格式为所有者/仓库名）
`token`	是	具备写权限的细粒度PAT（权限范围包括contents、issues、PRs、metadata）
`cache_key`	是	用于跨运行缓存结果的文件名（例如 `cached_results-mysite.json` ）
`login_url`	否	身份认证扫描的登录页面URL
`username`	否	身份认证用的用户名
`password`	否	身份认证用的密码（通过仓库Secret存储）
`auth_context`	否	复杂身份认证用的序列化JSON（Playwright会话状态）
`skip_copilot_assignment`	否	设置为 `true` 时跳过将Issue分配给Copilot
`include_screenshots`	否	设置为 `true` 时捕获截图（存储在 `gh-cache` 分支）

Parsing Scanner-Created Issues

解析扫描器生成的Issue

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

扫描器生成的GitHub Issue遵循结构化格式，Agent需要解析以下字段：

Issue Identification

Issue识别

Scanner-created issues can be identified by:

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

扫描器生成的Issue可以通过以下特征识别：

作者： 运行工作流的GitHub Actions机器人
标签： 扫描器会添加标签对发现的问题进行分类（通常是可访问性相关标签）
正文结构： Issue包含结构化的违规详情板块

Issue Body Structure

Issue正文结构

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

扫描器生成的Issue通常包含以下内容：

板块	内容	Agent用途
违规标题	被违反的axe-core规则	映射到 `help-url-reference` 获取修复文档
WCAG条款	具体的WCAG成功标准	用于严重程度评分和合规映射
受影响元素	违规元素的CSS选择器或HTML片段	由 `scanner-bridge` 用于映射到源代码
影响等级	Critical、Serious、Moderate或Minor	直接对应Agent的严重程度模型
修复指导	如何修复该问题	由Agent专家补充框架专属的修复方案
URL	发现问题的页面URL	用于与本地axe-core扫描结果交叉比对
截图链接	存储在 `gh-cache` 分支的截图链接（如果开启该功能）	包含在审计报告中

Severity Mapping

严重程度映射

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

扫描器使用的axe-core影响等级与Agent严重程度模型直接对应：

扫描器影响等级	Agent严重程度	权重分值
Critical	Critical	-15（双来源确认）/ -10（单来源）
Serious	Serious	-7（高置信度）
Moderate	Moderate	-3（高置信度）
Minor	Minor	-1

axe-core Rule Correlation

axe-core规则关联

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

扫描器底层基于axe-core实现，扫描器Issue标题和违规ID对应已收录在

help-url-reference

中的axe-core规则。常见的扫描器上报规则如下：

axe-core规则ID	WCAG条款	常见描述
`image-alt`	1.1.1	图片必须包含替代文本
`label`	1.3.1	表单元素必须有标签
`color-contrast`	1.4.3	元素必须有足够的颜色对比度
`link-name`	2.4.4	链接必须有可识别的文本
`html-has-lang`	3.1.1	`<html>` 元素必须包含lang属性
`button-name`	4.1.2	按钮必须有可识别的文本
`document-title`	2.4.2	文档必须包含 `<title>` 元素
`bypass`	2.4.1	页面必须提供跳过重复区块的方式
`heading-order`	1.3.1	标题层级应该逐级递增1
`aria-allowed-attr`	4.1.2	ARIA属性必须符合对应元素角色的使用规范

Caching and Delta Detection

缓存与差异检测

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

扫描器使用

cache_key

在工作流运行之间持久化结果，支持差异跟踪：

状态	含义
新增	当前扫描发现、但缓存结果中不存在的问题
已修复	缓存结果中存在、但当前扫描未发现的问题（Issue会自动关闭）
持续存在	当前扫描和缓存结果中都存在的问题

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

设置扫描器集成时，缓存键需要符合Agent的约定：

使用描述性命名：

cached_results-{域名}-{分支名}.json

包含分支上下文，用于分支专属扫描
缓存作为GitHub Actions构件存储

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:

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

当GitHub Accessibility Scanner（CI环境）和本地axe-core扫描（Agent）都发现同一问题时：

按规则ID匹配： 两个来源都使用axe-core规则ID（例如
```
color-contrast
```
、
```
image-alt
```
）
按URL匹配： 比对扫描器Issue中的扫描URL和本地扫描的目标URL
按元素匹配： 比对受影响元素的CSS选择器或HTML路径
提升置信度： 两个来源都确认的问题自动获得
```
high
```
置信度

Source Comparison Analysis

来源比对分析

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

场景	解读	处理动作
扫描器和本地扫描都发现	高置信度 -- 双来源确认	按高置信度上报，使用完整严重程度权重
仅扫描器发现	环境特有或偶现问题	按中等置信度上报，标注“仅CI环境发现”
仅本地扫描发现	上次CI扫描后新增的问题，或仅本地环境存在的问题	按中等置信度上报，标注“仅本地环境发现”
扫描器缓存标记为“已修复”	近期已修复	在差异部分标记为已解决

Copilot Fix Tracking

Copilot修复跟踪

When the scanner assigns issues to GitHub Copilot:

当扫描器将Issue分配给GitHub Copilot时：

Fix Lifecycle

修复生命周期

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

阶段	GitHub状态	检测方式
Issue已创建	Issue处于开放状态，已分配给Copilot	`assignee` 包含Copilot机器人
修复方案已提交	关联Issue的PR处于开放状态	PR引用了Issue编号，作者为Copilot
修复已评审	PR有评审评论	PR评审状态为 `CHANGES_REQUESTED` 或 `APPROVED`
修复已合并	PR已合并，Issue已关闭	Issue状态为 `closed` ，关联的PR已合并
修复被驳回	PR未合并已关闭	PR状态为 `closed` ，未合并

Querying Copilot Fix Status

查询Copilot修复状态

text

undefined

text

undefined

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

undefined

repo:{REPO} is:pr is:merged author:copilot-swe-agent label:accessibility

undefined

Structured Output Format

结构化输出格式

When

scanner-bridge

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

json

{
  "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"
}

当

scanner-bridge

标准化扫描器Issue数据时，会生成以下格式的结果：

json

{
  "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

扫描器Issue搜索模式

By Repository

按仓库搜索

text

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

text

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

同一次扫描运行生成的Issue拥有相同的创建时间戳和批次模式，可以通过以下条件过滤：

创建日期与工作流运行日期匹配
扫描器添加的通用标签集

Cross-Repository Scanner Discovery

跨仓库扫描器发现

text

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

text

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