github-a11y-scanner

GitHub Accessibility Scanner の統合

GitHub Accessibility Scanner とは？

GitHub Accessibility Scanner（github/accessibility-scanner@v2）は、以下の機能を備えた GitHub 公式の Action です。

• ヘッドレスブラウザーで axe-core を使用し、公開中の URL にあるアクセシビリティ上の障壁をスキャンします
• 検出結果ごとに、該当要素、WCAG 基準、修正方法のガイダンスを含む、追跡可能な GitHub Issue を作成します
• オプションで、AI を活用した修正案の提示や PR の作成を GitHub Copilot に割り当てます
• 実行間で結果をキャッシュし、差分（新規、修正済み、継続中の検出結果）を検出します
• 認証を伴うスキャン（ログインフロー、SSO、Playwright の auth context を介したパスキー）に対応します
• オプションでスクリーンショットを取得し、作成した 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 の作成先となるリポジトリ（owner/name）
token	はい	書き込みアクセス権（contents、issues、PRs、metadata）を持つ、きめ細かいアクセス許可の PAT
cache_key	はい	実行間で結果をキャッシュするためのファイル名（例：cached_results-mysite.json）
login_url	いいえ	認証を伴うスキャンに使用するログインページの URL
username	いいえ	認証に使用するユーザー名
password	いいえ	認証に使用するパスワード（リポジトリシークレット経由）
auth_context	いいえ	複雑な認証（Playwright のセッション状態）用の文字列化された JSON
skip_copilot_assignment	いいえ	Issue の Copilot への割り当てをスキップするには、true を設定します
include_screenshots	いいえ	スクリーンショットを取得するには、true を設定します（gh-cache ブランチに保存されます）

Scanner が作成した Issue の解析

Scanner は、構造化された形式の GitHub Issue を作成します。エージェントは次のフィールドを解析します。

Issue の識別

Scanner が作成した Issue は、次の方法で識別できます。

1. 作成者： ワークフローを実行する GitHub Actions ボット
2. ラベル： Scanner は検出結果を分類するためのラベル（通常はアクセシビリティ関連のラベル）を適用します
3. 本文の構造： Issue には違反の詳細を記載した構造化セクションが含まれます

Issue 本文の構造

Scanner の Issue には、通常次の内容が含まれます。

セクション	内容	エージェントでの用途
違反のタイトル	違反した axe-core ルール	修正ドキュメントの help-url-reference に対応付けます
WCAG 基準	該当する WCAG 達成基準	重大度のスコアリングとコンプライアンスの対応付けに使用します
該当要素	問題のある要素の CSS セレクターまたは HTML スニペット	scanner-bridge がソースコードに対応付けるために使用します
影響レベル	Critical、Serious、Moderate、Minor	エージェントの重大度モデルに直接対応します
修正方法のガイダンス	問題の修正方法	エージェントの専門家がフレームワーク固有の修正方法で補足します
URL	問題が見つかったページの URL	ローカルの axe-core スキャンとの相互参照に使用します
スクリーンショットのリンク	gh-cache ブランチにあるスクリーンショットへのリンク（有効な場合）	監査レポートに含めます

重大度の対応付け

Scanner は axe-core の影響レベルを使用し、エージェントの重大度モデルに直接対応付けます。

Scanner の影響度	エージェントの重大度	スコアの重み
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	見出しレベルは 1 つずつ順に上げる必要があります
aria-allowed-attr	4.1.2	ARIA 属性は要素のロールで許可されている必要があります

キャッシュと差分検出

スキャナーは cache_key を使用して、ワークフローの実行をまたいで結果を保持します。これにより、差分を追跡できます。

ステータス	意味
新規	現在のスキャンで見つかったが、キャッシュされた結果にはない問題
修正済み	キャッシュされた結果にはあるが、現在のスキャンでは見つからない問題（問題は自動的にクローズされます）
継続中	現在のスキャンとキャッシュされた結果の両方で見つかった問題

キャッシュキーの規則

スキャナー連携を設定するときは、エージェントの規則に合わせてキャッシュキーを設定します。

• 説明的な名前を使用します：cached_results-{domain}-{branch}.json
• ブランチごとのスキャンでは、ブランチのコンテキストを含めます
• キャッシュは GitHub Actions のアーティファクトとして保存されます

ローカルスキャンとの対応付け

2 つのソースによる信頼度の向上

GitHub Accessibility Scanner（CI）とローカルの axe-core スキャン（エージェント）の両方で同じ問題が見つかった場合：

1. ルール ID で照合： 両方のソースで axe-core のルール ID（例：color-contrast、image-alt）を使用します
2. URL で照合： スキャナーの問題に記載されたスキャン対象 URL と、ローカルスキャンの対象を比較します
3. 要素で照合： 影響を受ける要素の CSS セレクターまたは HTML パスを比較します
4. 信頼度を上げる： 両方のソースで確認された検出結果には、自動的に high の信頼度が付与されます

ソースの比較分析

シナリオ	解釈	対応
スキャナーとローカルスキャンの両方で検出	信頼度が高い — 両方で確認済み	信頼度を高として報告し、重大度を最大限に反映
スキャナーのみで検出	環境固有または断続的	信頼度を中として報告し、「CI のみで検出」と記載
ローカルスキャンのみで検出	前回の CI スキャン以降に発生、またはローカル固有の条件	信頼度を中として報告し、「ローカルのみで検出」と記載
スキャナーのキャッシュで「修正済み」	最近修正済み	差分のセクションで解決済みとして追跡

Copilot の修正追跡

スキャナーが問題を GitHub Copilot に割り当てた場合：

修正のライフサイクル

段階	GitHub の状態	検出方法
問題を作成	Copilot に割り当てられたオープンな issue	assignee に Copilot bot が含まれる
修正を提案	issue にリンクされたオープンな PR	PR が issue 番号を参照し、作成者が Copilot
修正をレビュー	PR にレビューコメントがある	PR のレビュー状態が CHANGES_REQUESTED または APPROVED
修正をマージ	PR がマージされ、issue がクローズ	issue の状態が 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