github/accessibility-scanner

Finds potential accessibility gaps, files GitHub issues to track them, and attempts to fix them with Copilot.

기능

AI 기반 접근성 스캐너는 웹 페이지(또는 지정한 URL)에 대해 자동 접근성 검사를 수행하는 GitHub Action입니다. AI 기반 도구(특히 GitHub Copilot)를 사용하여 각 발견 사항을 GitHub 이슈로 변환하고, Copilot가 활성화된 경우 인간이 병합 전 검토할 수 있는 수정용 풀 리퀘스트를 제안합니다.

왜 중요한가

WCAG 문제를 조기에 포착 – 스캐너는 트리거된 모든 워크플로에서 실행되므로, 접근성 회귀 문제가 프로덕션 코드에 머무르기 전에 발견됩니다.
검출 결과를 자동으로 작업 항목으로 전환 – 각 위반은 추적 가능한 이슈로 변환되며, 규칙이나 URL별로 선택적으로 그룹화되어 팀이 문제를 놓치지 않습니다.
AI를 활용해 빠른 수정 – Copilot를 사용하면 이 작업은 문제를 해결하는 PR을 초안으로 제안하여 일반적인 문제를 수정하는 데 필요한 수작업을 줄입니다.
기존 CI/CD에 쉽게 통합 – GitHub Actions 워크플로의 단순한 단계일 뿐이며, 쓰기 권한이 있는 PAT만 필요합니다.

사용 방법

.github/workflows/에 워크플로 파일을 추가합니다 (예: a11y-scan.yml).
스캔할 URL을 제공하거나, url_configs JSON을 사용해 대기할 선택자 또는 제외할 요소를 지정합니다.
이슈, PR, 리포지토리 쓰기 권한을 가진 세부적인 개인용 액세스 토큰(GH_TOKEN)을 제공합니다.
선택적 설정을 구성합니다 – 스크린샷 활성화, 이슈 그룹화, 스캔 엔진(axe, accesslint, 또는 사용자 정의 플러그인) 선택, 결과 미리보기용 드라이런 실행.
워크플로를 수동으로 또는 스케줄/PR 트리거로 실행합니다. 이 작업은 다음을 수행합니다:
- Playwright를 시작하고, 선택된 스캐너를 실행하여 발견 사항을 수집합니다.
- 각 발견 사항에 대해 GitHub 이슈를 생성합니다 (또는 group_by 설정에 따라 그룹화).
- Copilot가 활성화된 경우, 이슈를 Copilot에 할당하여 제안된 수정이 포함된 PR을 열 수 있도록 합니다.
- wontfix 레이블을 존중하여 닫힌 이슈가 다시 열리지 않도록 합니다.

누구에게 추천되는가

제품 및 프론트엔드 팀 – 자동 접근성 회귀 테스트를 원하는 팀.
오픈소스 유지보수자 – 기여자에게 접근성 버그를 노출하고 싶은 팀.
GitHub Copilot를 사용하는 조직 – AI의 도움을 접근성 수정에 확장하고 싶은 팀.
GitHub Actions를 사용하는 모든 리포지토리 – 작은 워크플로와 PAT를 추가할 수 있는 경우.

제한 사항 및 주의사항

스캐너는 공개 베타 중 – 기능은 변경될 수 있으며, 완전히 접근 가능한 코드를 보장하지 않습니다.
AI로 생성된 수정은 제안에 불과하며, 병합 전 반드시 검토해야 합니다.
자동 PR 생성은 GitHub Copilot에 의존합니다 – Copilot 없이도 이슈는 생성되지만, 자동 수정은 제공되지 않습니다.
스캔은 헤드리스 Playwright 환경에서 수행됩니다. 복잡한 인증이 필요한 페이지는 auth_context 입력이 필요할 수 있습니다.
이 작업은 스크린샷과 캐시된 결과를 위한 gh-cache 브랜치를 생성합니다. 이 브랜치는 리포지토리에 표시됩니다.

빠른 시작 체크리스트

✅ 대상 리포지토리에서 GitHub Actions와 이슈를 활성화합니다.
✅ actions, contents, issues, pull-requests, metadata 범위를 가진 세부적인 개인용 액세스 토큰을 생성합니다.
✅ GH_TOKEN이라는 이름의 시크릿으로 토큰을 추가합니다.
✅ 필요한 repository, token, cache_key 입력을 포함한 워크플로 파일을 추가합니다.
✅ (옵션) GitHub Copilot을 활성화하고, 더 나은 수정 제안을 위해 .github/copilot-instructions.md를 커스텀합니다.

모든 세부 정보는 리포지토리의 README에서 직접 가져왔습니다.