Repository files navigation

The AI-powered Accessibility Scanner (a11y scanner) is a GitHub Action that detects accessibility barriers across your digital products, creates trackable issues, and leverages GitHub Copilot for AI-powered fixes.

The a11y scanner helps teams:

• 🔍 Scan websites, files, repositories, and dynamic content for accessibility issues
• 📝 Create actionable GitHub issues that can be assigned to GitHub Copilot
• 🤖 Propose fixes with GitHub Copilot, with humans reviewing before merging

⚠️Note: The a11y scanner is currently in public preview. Feature development work is still ongoing. It can help identify accessibility gaps but cannot guarantee fully accessible code suggestions. Always review before merging!

🎥Watch the demo video to see the a11y scanner in action.

To use the a11y scanner, you'll need:

• GitHub Actions enabled in your repository
• GitHub Issues enabled in your repository
• Available GitHub Actions minutes for your account
• Admin access to add repository secrets
• GitHub Copilot (optional) - The a11y scanner works without GitHub Copilot and will still create issues for accessibility findings. However, without GitHub Copilot, you won't be able to automatically assign issues to GitHub Copilot for AI-powered fix suggestions and PR creation.

Create a workflow file in.github/workflows/ (e.g.,a11y-scan.yml) in your repository:

name:Accessibility Scanneron:workflow_dispatch# This configures the workflow to run manually, instead of (e.g.) automatically in every PR. Check out https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#on for more options.jobs:accessibility_scanner:runs-on:ubuntu-lateststeps:      -uses:github/accessibility-scanner@v2with:urls:|# Provide a newline-delimited list of URLs to scan; more information below.            REPLACE_THISrepository:REPLACE_THIS/REPLACE_THIS# Provide a repository name-with-owner (in the format "primer/primer-docs"). This is where issues will be filed and where Copilot will open PRs; more information below.token:${{ secrets.GH_TOKEN }}# This token must have write access to the repo above (contents, issues, and PRs); more information below. Note: GitHub Actions' GITHUB_TOKEN cannot be used here.cache_key:REPLACE_THIS# Provide a filename that will be used when caching results. We recommend including the name or domain of the site being scanned.# login_url: # Optional: URL of the login page if authentication is required# username: # Optional: Username for authentication# password: ${{ secrets.PASSWORD }} # Optional: Password for authentication (use secrets!)# auth_context: # Optional: Stringified JSON object for complex authentication# skip_copilot_assignment: false # Optional: Set to true to skip assigning issues to GitHub Copilot (or if you don't have GitHub Copilot)

👉 Update allREPLACE_THIS placeholders with your actual values. SeeAction Inputs for details.

Required permissions:

• Write access to add or update workflows
• Admin access to add repository secrets

📚 Learn more

• Quickstart for GitHub Actions
• Understanding GitHub Actions
• Writing workflows
• Managing GitHub Actions settings
• GitHub Actions billing

The a11y scanner requires a Personal Access Token (PAT) as a repository secret:

TheGH_TOKEN is a fine-grained PAT with:

• actions: write
• contents: write
• issues: write
• pull-requests: write
• metadata: read
• Scope: Your target repository (where issues and PRs will be created) and the repository containing your workflow

👉 GitHub Actions' defaultGITHUB_TOKEN cannot be used here.

📚 Learn more

• Creating a fine-grained PAT
• Creating repository secrets

Trigger the workflow manually or automatically based on your configuration. The a11y scanner will run and create issues for any accessibility findings. When issues are assigned to GitHub Copilot, always review proposed fixes before merging.

📚 Learn more

• View workflow run history
• Running a workflow manually
• Re-run workflows and jobs

If access to a page requires logging-in first, and logging-in requires only a username and password, then provide thelogin_url,username, andpassword inputs.

If your login flow is more complex—if it requires two-factor authentication, single sign-on, passkeys, etc.—and you have a custom action thatauthenticates with Playwright and persists authenticated session state to a file, then provide theauth_context input. (Ifauth_context is provided,login_url,username, andpassword will be ignored.)

The a11y scanner leverages GitHub Copilot coding agent, which can be configured with custom instructions:

• Repository-wide:.github/copilot-instructions.md
• Directory/file-scoped:.github/instructions/*.instructions.md

📚 Learn more

• Adding repository custom instructions
• Optimizing GitHub Copilot for accessibility
• GitHub Copilot .instructions.md support
• GitHub Copilot agents.md support

💬 We welcome your feedback! To submit feedback or report issues, please create an issue in this repository. For more information on contributing, please refer to theCONTRIBUTING file.

📄 This project is licensed under the terms of the MIT open source license. Please refer to theLICENSE file for the full terms.

🔧 Please refer to theCODEOWNERS file for more information.

❓ Please refer to theSUPPORT file for more information.

✨ Thank you to our beta testers for their help with making this project!