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
@@ -89,6 +90,7 @@ The a11y scanner requires a Personal Access Token (PAT) as a repository secret:
89
90
> 👉 GitHub Actions' default [GITHUB_TOKEN](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) cannot be used here.
90
91
91
92
📚 Learn more
93
+
92
94
-[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)
@@ -99,6 +101,7 @@ The a11y scanner requires a Personal Access Token (PAT) as a repository secret:
99
101
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.
100
102
101
103
📚 Learn more
104
+
102
105
-[View workflow run history](https://docs.github.com/en/actions/how-tos/monitor-workflows/view-workflow-run-history)
103
106
-[Running a workflow manually](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#running-a-workflow)
104
107
-[Re-run workflows and jobs](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs)
@@ -107,20 +110,21 @@ Trigger the workflow manually or automatically based on your configuration. The
107
110
108
111
## Action inputs
109
112
110
-
| Input | Required | Description | Example |
111
-
|-------|----------|-------------|---------|
112
-
|`urls`| Yes | Newline-delimited list of URLs to scan |`https://primer.style`<br>`https://primer.style/octicons`|
113
-
|`repository`| Yes | Repository (with owner) for issues and PRs |`primer/primer-docs`|
114
-
|`token`| Yes | PAT with write permissions (see above) |`${{ secrets.GH_TOKEN }}`|
115
-
|`cache_key`| Yes | Key for caching results across runs<br>Allowed: `A-Za-z0-9._/-`|`cached_results-primer.style-main.json`|
116
-
|`login_url`| No | If scanned pages require authentication, the URL of the login page |`https://github.com/login`|
117
-
|`username`| No | If scanned pages require authentication, the username to use for login |`some-user`|
118
-
|`password`| No | If scanned pages require authentication, the password to use for login |`${{ secrets.PASSWORD }}`|
119
-
|`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":[...]}`|
120
-
|`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`|
121
-
|`include_screenshots`| No | Whether to capture screenshots of scanned pages and include links to them in filed issues. Screenshots are stored on the `gh-cache` branch of the repository running the workflow. Default: `false`|`true`|
122
-
|`reduced_motion`| No | Playwright `reducedMotion` setting for scan contexts. Allowed values: `reduce`, `no-preference`|`reduce`|
123
-
|`color_scheme`| No | Playwright `colorScheme` setting for scan contexts. Allowed values: `light`, `dark`, `no-preference`|`dark`|
|`urls`| Yes | Newline-delimited list of URLs to scan |`https://primer.style`<br>`https://primer.style/octicons`|
116
+
|`repository`| Yes | Repository (with owner) for issues and PRs |`primer/primer-docs`|
117
+
|`token`| Yes | PAT with write permissions (see above) |`${{ secrets.GH_TOKEN }}`|
118
+
|`cache_key`| Yes | Key for caching results across runs<br>Allowed: `A-Za-z0-9._/-`|`cached_results-primer.style-main.json`|
119
+
|`login_url`| No | If scanned pages require authentication, the URL of the login page |`https://github.com/login`|
120
+
|`username`| No | If scanned pages require authentication, the username to use for login |`some-user`|
121
+
|`password`| No | If scanned pages require authentication, the password to use for login |`${{ secrets.PASSWORD }}`|
122
+
|`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":[...]}`|
123
+
|`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`|
124
+
|`include_screenshots`| No | Whether to capture screenshots of scanned pages and include links to them in filed issues. Screenshots are stored on the `gh-cache` branch of the repository running the workflow. Default: `false`|`true`|
125
+
|`reduced_motion`| No | Playwright `reducedMotion` setting for scan contexts. Allowed values: `reduce`, `no-preference`|`reduce`|
126
+
|`color_scheme`| No | Playwright `colorScheme` setting for scan contexts. Allowed values: `light`, `dark`, `no-preference`|`dark`|
127
+
|`scans`| No | A list of scans (or plugins) to be performed. If not provided, only axe will be performed. |`['axe', 'reflow']`|
124
128
125
129
---
126
130
@@ -143,13 +147,46 @@ The a11y scanner leverages GitHub Copilot coding agent, which can be configured
The plugin system allows teams to create custom scans/test to run on their pages. An example of this is axe interaction tests. In some cases, it might be desirable to perform specific interactions on elements of a given page before doing an axe scan. These interactions are usually unique to each page that is scanned, so it would require the owning team to write a custom plugin that can interact with the page and run the axe scan when ready. See the example under `./.github/scanner-plugins/test-plugin` (this is not an axe interaction test, but should give a general understanding of how plugins look like).
161
+
162
+
Some plugins come built-in with the scanner and can be enabled via actions inputs.
163
+
164
+
### How Plugins Work
165
+
166
+
Plugins are dynamically loaded by the scanner when it runs. The scanner will look into the `./.github` folder in your repo (where you run the workflow from) and search for a `scanner-plugins` folder. If it finds it, it will assume each folder under that is a plugin, and attempt to load the `index.js` file inside it. Once loaded, the scanner will invoke the exported default function from the `index.js` file.
167
+
168
+
#### Default Function Api
169
+
170
+
When the default function is invoked, the following arguments are passed to the function:
171
+
172
+
- page: this is the [playwright page](https://playwright.dev/docs/api/class-page) instance. See the linked docs for information on how to interact with the page.
173
+
- addFinding: this is a function that will add a finding to the list. Findings are used to generate issues and 'filings'. See here for the [types](https://github.com/github/accessibility-scanner/blob/main/tests/types.d.ts). This function expects a single object as an argument, and it should match the `Finding` type defined in the types linked above.
174
+
175
+
### How To Create Plugins
176
+
177
+
As mentioned above, plugins need to live under `./.github/scanner-plugins`. For a plugin to work, it needs to meet the following criteria:
178
+
179
+
- Each seperate plugin should live in a separate folder under `./.github/scanner-plugins`. So `./.github/scanner-plugins/plugin-1` would be 1 plugin loaded by the scanner
180
+
- Each plugin should have one `index.js` file inside its folder
181
+
- The `index.js` file must export a `name` field. This is the name used to pass to the `scans` input. So the following: `scans: ['my-custom-plugin']` would cause the scanner to only run that plugin
182
+
- The `index.js` file must export a default function. This is the function that the scanner uses to run the plugin.
183
+
184
+
### Things To Lookout For
185
+
186
+
- Plugin names should be unique. If multiple plugins have the same name, and the `scans` input passes this name, all the plugins with that name _will_ run. However, this is not advised because if you want to turn off one plugin, you'll have to go back and change that plugin name.
187
+
188
+
---
189
+
153
190
## Feedback
154
191
155
192
💬 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.
0 commit comments