You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The AI-powered Accessibility Scanner (a11y scanner) is a GitHub Action that detects accessibility barriers across your digital products, creates trackable issues, and leverages Copilot for AI-powered fixes.
3
+
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.
4
4
5
5
The a11y scanner helps teams:
6
6
7
7
- 🔍 Scan websites, files, repositories, and dynamic content for accessibility issues
8
-
- 📝 Create actionable GitHub issues that can be assigned to Copilot
9
-
- 🤖 Propose fixes with Copilot, with humans reviewing before merging
8
+
- 📝 Create actionable GitHub issues that can be assigned to GitHub Copilot
9
+
- 🤖 Propose fixes with GitHub Copilot, with humans reviewing before merging
10
10
11
-
> ⚠️ **Note:** The a11y scanner is currently in beta. It can help identify accessibility gaps but cannot guarantee fully accessible code suggestions. Always review before merging!
11
+
> ⚠️ **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!
12
+
13
+
🎥 **[Watch the demo video](https://youtu.be/CvRJcEzCSQM)** to see the a11y scanner in action.
12
14
13
15
---
14
16
15
17
## Requirements
16
18
17
-
This project is a GitHub Actions action. A GitHub Actions workflow is required to run it, and you must have available GitHub Actions minutes.
19
+
To use the a11y scanner, you'll need:
20
+
21
+
-**GitHub Actions** enabled in your repository
22
+
-**GitHub Issues** enabled in your repository
23
+
-**Available GitHub Actions minutes** for your account
24
+
-**Admin access** to add repository secrets
25
+
-**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:
25
32
26
-
```YAML
33
+
```yaml
27
34
name: Accessibility Scanner
28
35
on: 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.
29
36
@@ -36,49 +43,64 @@ jobs:
36
43
urls: | # Provide a newline-delimited list of URLs to scan; more information below.
37
44
REPLACE_THIS
38
45
repository: 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.
39
-
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` (https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) cannot be used here.
40
-
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 scanning.
46
+
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.
47
+
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.
48
+
# login_url: # Optional: URL of the login page if authentication is required
49
+
# username: # Optional: Username for authentication
The a11y scanner requires a Personal Access Token (PAT) as repository secret:
73
+
The a11y scanner requires a Personal Access Token (PAT) as a repository secret:
57
74
58
-
#### The `GH_TOKEN` is a fine-grained PAT with
75
+
**The `GH_TOKEN` is a fine-grained PAT with:**
59
76
60
77
-`actions: write`
61
78
-`contents: write`
62
79
-`issues: write`
63
80
-`pull-requests: write`
64
81
-`metadata: read`
65
-
- Scope: Your target repository (where issues and PRs will be created) and the repository containing your workflow
82
+
-**Scope:** Your target repository (where issues and PRs will be created) and the repository containing your workflow
66
83
67
-
> 👉 GitHub Actions' default `GITHUB_TOKEN` cannot be used here.
84
+
> 👉 GitHub Actions' default [GITHUB_TOKEN](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) cannot be used here.
68
85
69
-
📚 [Creating a fine-grained PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) | [Creating repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository)
86
+
📚 Learn more
87
+
-[Creating a fine-grained PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)
Trigger the workflow manually or automatically based on your configuration. The scanner will run and create issues for any accessibility findings. When issues are assigned to Copilot, always review proposed fixes before merging.
94
+
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.
76
95
77
-
📚 [Running a workflow manually](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#running-a-workflow)
96
+
📚 Learn more
97
+
-[View workflow run history](https://docs.github.com/en/actions/how-tos/monitor-workflows/view-workflow-run-history)
98
+
-[Running a workflow manually](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#running-a-workflow)
99
+
-[Re-run workflows and jobs](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs)
78
100
79
101
---
80
102
81
-
## Action Inputs
103
+
## Action inputs
82
104
83
105
| Input | Required | Description | Example |
84
106
|-------|----------|-------------|---------|
@@ -88,54 +110,54 @@ Trigger the workflow manually or automatically based on your configuration. The
88
110
|`cache_key`| Yes | Key for caching results across runs<br>Allowed: `A-Za-z0-9._/-`|`cached_results-primer.style-main.json`|
89
111
|`login_url`| No | If scanned pages require authentication, the URL of the login page |`https://github.com/login`|
90
112
|`username`| No | If scanned pages require authentication, the username to use for login |`some-user`|
91
-
| `password` | No | If scanned pages require authentication, the password to use for login | `correct-horse-battery-staple` |
92
-
| `auth_context` | No | If scanned pages require authentication, a stringified JSON object containing username, password, cookies, and/or localStorage from an authenticated session | `{"username":"some-user","password":"correct-horse-battery-staple","cookies":[{"name":"theme-preference","value":"light","domain":"primer.style","path":"/"}],"localStorage":{"https://primer.style":{"theme-preference":"light"}}}` |
93
-
| `skip_copilot_assignment` | No | Whether to skip assigning filed issues to Copilot | `true` |
113
+
|`password`| No | If scanned pages require authentication, the password to use for login |`${{ secrets.PASSWORD }}`|
114
+
|`auth_context`| No | If scanned pages require authentication, a stringified JSON object containing username, password, cookies, and/or localStorage from an authenticated session |`{"username":"some-user","password":"***","cookies":[...]}`|
115
+
|`skip_copilot_assignment`| No | Whether to skip assigning filed issues to GitHub Copilot. Set to `true` if you don't have GitHub Copilot or prefer to handle issues manually|`true`|
94
116
95
117
---
96
118
97
119
## Authentication
98
120
99
121
If access to a page requires logging-in first, and logging-in requires only a username and password, then provide the `login_url`, `username`, and `password` inputs.
100
122
101
-
If your login flow is more complex—if it requires two-factor authentication, single sign-on, passkeys, etc.–and you have a custom action that [authenticates with Playwright](https://playwright.dev/docs/auth) and persists authenticated session state to a file, then provide the `auth_context` input. (If `auth_context` is provided, `login_url`, `username`, and `password` will be ignored.)
123
+
If your login flow is more complex—if it requires two-factor authentication, single sign-on, passkeys, etc.—and you have a custom action that [authenticates with Playwright](https://playwright.dev/docs/auth) and persists authenticated session state to a file, then provide the `auth_context` input. (If `auth_context` is provided, `login_url`, `username`, and `password` will be ignored.)
102
124
103
125
> [!IMPORTANT]
104
-
> Don’t put passwords in your workflow as plain text; instead reference a [repository secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository).
126
+
> Don't put passwords in your workflow as plain text; instead reference a [repository secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository).
105
127
106
128
---
107
129
108
-
## Configuring Copilot
130
+
## Configuring GitHub Copilot
109
131
110
-
The a11y scanner leverages Copilot coding agent, which can be configured with custom instructions:
132
+
The a11y scanner leverages GitHub Copilot coding agent, which can be configured with custom instructions:
Please refer to the [CONTRIBUTING](./CONTRIBUTING.md) file for more information.
147
+
💬 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 the [CONTRIBUTING](./CONTRIBUTING.md) file.
122
148
123
149
## License
124
150
125
-
This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.
151
+
📄 This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.
126
152
127
153
## Maintainers
128
154
129
-
Please refer to the [CODEOWNERS](./.github/CODEOWNERS) file for more information.
155
+
🔧 Please refer to the [CODEOWNERS](./.github/CODEOWNERS) file for more information.
130
156
131
157
## Support
132
158
133
-
Please refer to the [SUPPORT](./SUPPORT.md) file for more information.
159
+
❓ Please refer to the [SUPPORT](./SUPPORT.md) file for more information.
134
160
135
161
## Acknowledgement
136
162
137
-
Thank you to our beta testers for their help in testing this project.
138
-
139
-
---
140
-
141
-
*Last updated: 2025-10-09*
163
+
✨ Thank you to our beta testers for their help making this project!
0 commit comments