github-a11y-scanner

GitHub Accessibility Scanner 集成

什么是 GitHub Accessibility Scanner？

GitHub Accessibility Scanner（github/accessibility-scanner@v2）是 GitHub 官方的 Action，可用于：

• 在无头浏览器中使用 axe-core 扫描在线 URL，查找无障碍障碍
• 为每项发现的问题创建可跟踪的 GitHub Issue，其中包含受影响的元素、WCAG 准则和修复指导
• 可选地将 Issue 分配给 GitHub Copilot，以获取 AI 驱动的修复建议并创建 PR
• 跨运行缓存结果，以检测变化（新增、已修复、持续存在的问题）
• 支持经过身份验证的扫描（通过 Playwright 身份验证上下文处理登录流程、SSO 和通行密钥）
• 可选地截取屏幕截图并将其附加到已创建的 Issue

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

检测 Scanner 是否存在

要确定仓库是否已配置 GitHub Accessibility Scanner：

检测工作流文件

搜索引用该 Scanner Action 的工作流文件：

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

要在 YAML 中匹配的模式：

- uses: github/accessibility-scanner@v2

工作流输入

找到 Scanner 工作流后，提取其配置：

输入	必需	说明
urls	是	要扫描的 URL 列表，每行一个
repository	是	创建 Issue 和 PR 的仓库（所有者/名称）
token	是	具有写入权限（contents、issues、PR 和 metadata）的细粒度 PAT
cache_key	是	用于跨运行缓存结果的文件名（例如，cached_results-mysite.json）
login_url	否	用于经过身份验证的扫描的登录页面 URL
username	否	用于身份验证的用户名
password	否	用于身份验证的密码（通过仓库密钥提供）
auth_context	否	复杂身份验证所需的 JSON 字符串（Playwright 会话状态）
skip_copilot_assignment	否	设为 true 可跳过将 Issue 分配给 Copilot
include_screenshots	否	设为 true 可截取屏幕截图（存储在 gh-cache 分支上）

解析 Scanner 创建的 Issue

Scanner 创建的 GitHub Issue 采用结构化格式。Agent 应解析以下字段：

Issue 标识

可通过以下方式识别 Scanner 创建的 Issue：

1. 作者： 运行该工作流的 GitHub Actions 机器人
2. 标签： Scanner 会应用标签对发现的问题进行分类（通常是与无障碍相关的标签）
3. 正文结构： Issue 包含列出违规详情的结构化部分

Issue 正文结构

Scanner 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 分支上屏幕截图的链接（如已启用）	纳入审计报告

严重性映射

Scanner 使用 axe-core 影响级别，可直接映射到 Agent 严重性模型：

Scanner 影响级别	Agent 严重性	分值权重
Critical	Critical	-15（双来源）/-10（单一来源）
Serious	Serious	-7（高置信度）
Moderate	Moderate	-3（高置信度）
Minor	Minor	-1

axe-core 规则对应关系

扫描器在底层使用 axe-core。扫描器问题标题和违规 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	标题级别应逐级递增
aria-allowed-attr	4.1.2	ARIA 属性必须适用于元素角色

缓存和差异检测

扫描器使用 cache_key 在不同工作流运行之间持久保存结果，从而实现差异跟踪：

状态	含义
New	在当前扫描中发现问题，但缓存结果中没有
Fixed	缓存结果中有问题，但当前扫描未发现（问题已自动关闭）
Persistent	当前扫描和缓存结果中都发现了问题

缓存键约定

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

• 使用描述性名称：cached_results-{domain}-{branch}.json
• 按分支扫描时包含分支上下文
• 缓存以 GitHub Actions 构件的形式存储

与本地扫描的关联

双源置信度提升

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

1. 按规则 ID 匹配： 两个来源都使用 axe-core 规则 ID（例如 color-contrast、image-alt）
2. 按 URL 匹配： 将扫描器问题中的已扫描 URL 与本地扫描目标进行比较
3. 按元素匹配： 比较受影响元素的 CSS 选择器或 HTML 路径
4. 提升置信度： 两个来源都确认的发现会自动获得 high 置信度

来源比较分析

情况	解读	操作
扫描器和本地扫描都发现	高置信度——已由双方确认	报告为高置信度，采用完整严重性权重
仅扫描器发现	特定于环境或间歇性出现	报告为中置信度，并注明“仅 CI 中发现”
仅本地扫描发现	CI 上次扫描后新出现，或仅在本地存在的情况	报告为中置信度，并注明“仅本地发现”
扫描器缓存中标记为“fixed”	最近已修复	在差异部分跟踪为已解决

Copilot 修复跟踪

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

修复生命周期

阶段	GitHub 状态	检测方式
创建问题	已打开的问题，已分配给 Copilot	assignee 包含 Copilot 机器人
提出修复	有关联问题的已打开 PR	PR 引用了问题编号，作者为 Copilot
审查修复	PR 有审查评论	PR 审查状态为 CHANGES_REQUESTED 或 APPROVED
合并修复	PR 已合并，问题已关闭	问题状态为 closed，关联 PR 已合并
拒绝修复	PR 已关闭但未合并	PR 状态为 closed，且未合并

查询 Copilot 修复状态

# 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

结构化输出格式

当 scanner-bridge 规范化扫描器问题数据时，会以以下格式生成发现结果：

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

按扫描运行搜索

特定扫描运行中的问题具有相同的创建时间戳和批次模式。可按以下条件筛选：

• 创建日期与工作流运行日期一致
• 扫描器应用的通用标签集

跨仓库扫描器发现

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