From 476d2c8b43c9090781adc94224fc842aee1412d8 Mon Sep 17 00:00:00 2001 From: Joyce Zhu Date: Fri, 27 Feb 2026 02:08:46 -0500 Subject: [PATCH 1/5] Add more documentation for the following: - what the `gh-cache` branch is for - PDF scanning is outside our scope --- FAQ.md | 31 +++++++++++++++++++++++++++++++ README.md | 8 +++++--- 2 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 FAQ.md diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..257ed3a --- /dev/null +++ b/FAQ.md @@ -0,0 +1,31 @@ +# [Frequently-Asked Questions (FAQ)] + +## `find` Action (Scanning for problems) + +### Do you support scanning PDFs? + +We're focusing this Action on website accessibility and currently don't plan to +add PDF scanning capabilities. + +If you're looking to scan PDFs, we recommend using one of the +[standalone PDF accessibility checkers listed by the PDF +Association](https://pdfa.org/tools-for-accessible-pdf/). + +## Other / repository-wide questions + +### What is the `gh-cache` branch/Action for? + +Short answer: This is an orphan branch for storing information between Actions +runs. It's an implementation detail and can be safely ignored by users. + +Longer answer: We use the `gh-cache` branch and [its associated +Action](https://github.com/github/accessibility-scanner/tree/066e45c819d270bfb2392cfe141b570131c8011b/.github/actions/gh-cache) +to persist issue data between action runs, which both prevents opening duplicate +issues and allows us to automatically close issues which have been fixed +(in other words, if a problem wasn't detected again in an ensuing run, it is +therefore no longer a problem). + +Using a `git` branch as a caching mechanism allows users to view and/or edit the current +contents of the cache through the usual GitHub user interface. It also means the +contents of the cache are version controlled and can be changed through the +`git` commands users are accustomed to. diff --git a/README.md b/README.md index 3c9cebc..3d64467 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The AI-powered Accessibility Scanner (a11y scanner) is a GitHub Action that dete The a11y scanner helps teams: -- 🔍 Scan websites, files, repositories, and dynamic content for accessibility issues +- 🔍 Scan websites, 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 @@ -14,6 +14,8 @@ The a11y scanner helps teams: --- +## [Frequently-Asked Questions (FAQ)](FAQ.md) + ## Requirements To use the a11y scanner, you'll need: @@ -148,11 +150,11 @@ The a11y scanner leverages GitHub Copilot coding agent, which can be configured 💬 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. -## License +## License 📄 This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms. -## Maintainers +## Maintainers 🔧 Please refer to the [CODEOWNERS](./.github/CODEOWNERS) file for more information. From 839f18cbb3c8319e091ec652da04315731f85c0f Mon Sep 17 00:00:00 2001 From: Carie Fisher <15240149+cehfisher@users.noreply.github.com> Date: Fri, 27 Feb 2026 07:30:11 -0600 Subject: [PATCH 2/5] Update FAQ.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hi @JoyceZhu – I made some edits to your draft doc. Please review and update anything that doesn't make sense! --- FAQ.md | 98 +++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 77 insertions(+), 21 deletions(-) diff --git a/FAQ.md b/FAQ.md index 257ed3a..a7ebc2f 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,31 +1,87 @@ -# [Frequently-Asked Questions (FAQ)] +# FAQ -## `find` Action (Scanning for problems) +## Find Action (Scanning for Problems) ### Do you support scanning PDFs? -We're focusing this Action on website accessibility and currently don't plan to -add PDF scanning capabilities. +Not at this time — our focus is on **website accessibility**, so PDF scanning isn't something we're planning to build into this Action. -If you're looking to scan PDFs, we recommend using one of the -[standalone PDF accessibility checkers listed by the PDF -Association](https://pdfa.org/tools-for-accessible-pdf/). +That said, there are great tools out there for that! We'd suggest checking out the standalone PDF accessibility checkers listed by the [PDF Association](https://www.pdfa.org/). -## Other / repository-wide questions +### What about mobile apps, documents, or email templates? -### What is the `gh-cache` branch/Action for? +This Action is built specifically to scan **websites, repositories, and dynamic content** for accessibility issues. We don't support scanning for: -Short answer: This is an orphan branch for storing information between Actions -runs. It's an implementation detail and can be safely ignored by users. +- **Mobile apps** (iOS or Android) +- **Desktop applications** +- **Documents** (Word, PowerPoint, Excel, etc.) +- **Email templates** -Longer answer: We use the `gh-cache` branch and [its associated -Action](https://github.com/github/accessibility-scanner/tree/066e45c819d270bfb2392cfe141b570131c8011b/.github/actions/gh-cache) -to persist issue data between action runs, which both prevents opening duplicate -issues and allows us to automatically close issues which have been fixed -(in other words, if a problem wasn't detected again in an ensuing run, it is -therefore no longer a problem). +If you need accessibility testing for those, there are dedicated tools better suited for each — but for catching web accessibility problems before they reach your users, that's exactly what we're here for. -Using a `git` branch as a caching mechanism allows users to view and/or edit the current -contents of the cache through the usual GitHub user interface. It also means the -contents of the cache are version controlled and can be changed through the -`git` commands users are accustomed to. +--- + +## Other / Repository-Wide Questions + +### What's the `gh-cache` branch/Action all about? + +**The short version:** It's an orphan branch we use to store data between Action runs. You can safely ignore it — it's just a behind-the-scenes detail. + +**The longer version:** We use the `gh-cache` branch (and its associated Action) to keep track of issue data across runs. This is what prevents the Action from opening duplicate issues, and it's also how we're able to **automatically close issues** that have been fixed — if a problem isn't detected again on a subsequent run, we treat it as resolved. + +Why a git branch instead of some other caching method? A couple of reasons: + +- You can view and edit the cache contents right in the GitHub UI — no extra tooling needed. +- Everything is version-controlled, so you can manage it with the same git commands you already know. + +### Does this work with private repositories? + +Yes! The Action works with both public and private repositories. Since it runs within GitHub Actions, it has access to your repository's content regardless of visibility settings. No extra configuration needed. + +### Does this work with monorepos or multiple sites? + +It does. If your repository contains multiple sites or projects, you can configure separate workflow runs targeting different URLs or paths. Each scan runs independently, so you can tailor the setup to match however your repo is structured. + +### How often does / should the Action run? + +That's really up to you and your workflow. Some common setups include: + +- **On every push or pull request** — great for catching issues early in development +- **On a scheduled cron job** (e.g., daily or weekly) — good for ongoing monitoring of live sites +- **Manually triggered** — useful for one-off audits + +If you're just getting started, running on pull requests is a solid default — it catches problems before they get merged without adding noise to every single commit. + +### Will this slow down my CI/CD pipeline? + +The Action runs as its own job, so it won't block your builds or deployments unless you specifically configure it to. Scan times depend on the size and complexity of the site being scanned, but for most projects it adds minimal overhead. You can also run it on a schedule instead of on every push if speed is a concern. + +### Can I customize which rules or checks are run? + +Under the hood, this Action uses **[axe-core](https://github.com/dequelabs/axe-core)** — the industry gold standard for automated accessibility testing. That gives you a solid, well-maintained foundation right out of the box. + +That said, you're not locked into a single setup. You can tap into different APIs and configure the Action to focus on the specific accessibility standards or rules that matter most to your project. + +If you're looking to go even further, we also have resources for integrating accessibility into your development workflow with GitHub Copilot: + +- **[Getting Started with GitHub Copilot Custom Agents for Accessibility](https://accessibility.github.com/documentation/guide/getting-started-with-agents/)** — learn how to set up custom agents tailored to accessibility workflows +- **[Optimizing GitHub Copilot for Accessibility with Custom Instructions](https://accessibility.github.com/documentation/guide/copilot-instructions/)** — fine-tune how Copilot assists you with accessibility-specific guidance + +Between axe-core's rule set, API flexibility, and Copilot's custom instructions, you've got a lot of room to shape the tooling around how your team actually works. + +### Does this work with GitHub Enterprise? + +Yes, the Action is compatible with GitHub Enterprise Cloud. For GitHub Enterprise Server, compatibility may depend on your version and Actions availability. If you run into any issues, feel free to open an issue and we'll do our best to help. + +### How do I remove or reset the cache? + +Since the cache lives on the `gh-cache` branch, you have a couple of options: + +- **Delete the branch entirely** — the Action will create a fresh one on its next run +- **Edit or remove specific files** on the branch through the GitHub UI or git commands + +Just keep in mind that resetting the cache means the Action will "forget" what it's already seen, so it may reopen issues that were previously tracked or closed. + +### Can multiple people use this on the same repo? + +Absolutely. The Action is tied to the repository, not to any individual user. Anyone with the appropriate permissions can trigger runs, view results, and manage the issues it creates. It works just like any other GitHub Action in that regard. From f8ec0babbcee72b0cf728e74323082463ee05d7a Mon Sep 17 00:00:00 2001 From: Carie Fisher <15240149+cehfisher@users.noreply.github.com> Date: Fri, 27 Feb 2026 07:31:21 -0600 Subject: [PATCH 3/5] Add section on deciding future features Added a section explaining how feature requests are prioritized. --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 3d64467..3a2c960 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,19 @@ The a11y scanner leverages GitHub Copilot coding agent, which can be configured 💬 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. +## How We Decide What to Build Next + +We love hearing ideas and suggestions from the community — your feedback genuinely helps shape our thinking. That said, we want to be upfront: **there's no guarantee that any specific feature request will be implemented.** + +Our team prioritizes upcoming work based on a number of factors, including: + +- Alignment with the Action's core mission (website accessibility scanning) +- The complexity and scope of the work involved +- How many users would benefit from the change +- Our current bandwidth and roadmap commitments + +We read every suggestion and appreciate the time people take to share them. Even if we can't act on a request right away (or at all), it still helps us understand what matters most to the people using this tool. So please keep the ideas coming — just know that we can't make promises about what will or won't ship. + ## License 📄 This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms. From e3ce10a86936e512a4fa601e35feb01c175e75b8 Mon Sep 17 00:00:00 2001 From: Joyce Zhu Date: Fri, 27 Feb 2026 13:29:06 -0500 Subject: [PATCH 4/5] Reorganizing: - line wrapping - restore more specific link - move the caching question to directly follow the "what is the `gh-cache` branch for" question --- FAQ.md | 112 ++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 80 insertions(+), 32 deletions(-) diff --git a/FAQ.md b/FAQ.md index a7ebc2f..44e6397 100644 --- a/FAQ.md +++ b/FAQ.md @@ -4,20 +4,26 @@ ### Do you support scanning PDFs? -Not at this time — our focus is on **website accessibility**, so PDF scanning isn't something we're planning to build into this Action. +Not at this time — our focus is on **website accessibility**, so PDF scanning +isn't something we're planning to build into this Action. -That said, there are great tools out there for that! We'd suggest checking out the standalone PDF accessibility checkers listed by the [PDF Association](https://www.pdfa.org/). +That said, there are great tools out there for that! We'd suggest checking out +the [standalone PDF accessibility checkers listed by the PDF +Association](https://pdfa.org/tools-for-accessible-pdf/). ### What about mobile apps, documents, or email templates? -This Action is built specifically to scan **websites, repositories, and dynamic content** for accessibility issues. We don't support scanning for: +This Action is built specifically to scan **websites, repositories, and dynamic +content** for accessibility issues. We don't support scanning for: - **Mobile apps** (iOS or Android) - **Desktop applications** - **Documents** (Word, PowerPoint, Excel, etc.) - **Email templates** -If you need accessibility testing for those, there are dedicated tools better suited for each — but for catching web accessibility problems before they reach your users, that's exactly what we're here for. +If you need accessibility testing for those, there are dedicated tools better +suited for each — but for catching web accessibility problems before they reach +your users, that's exactly what we're here for. --- @@ -25,63 +31,105 @@ If you need accessibility testing for those, there are dedicated tools better su ### What's the `gh-cache` branch/Action all about? -**The short version:** It's an orphan branch we use to store data between Action runs. You can safely ignore it — it's just a behind-the-scenes detail. +**The short version:** It's an orphan branch we use to store data between Action +runs. You can safely ignore it — it's just a behind-the-scenes detail. -**The longer version:** We use the `gh-cache` branch (and its associated Action) to keep track of issue data across runs. This is what prevents the Action from opening duplicate issues, and it's also how we're able to **automatically close issues** that have been fixed — if a problem isn't detected again on a subsequent run, we treat it as resolved. +**The longer version:** We use the `gh-cache` branch (and its associated Action) +to keep track of issue data across runs. This is what prevents the Action from +opening duplicate issues, and it's also how we're able to **automatically close +issues** that have been fixed — in other words, if a problem isn't detected +again on a subsequent run, we treat it as resolved. -Why a git branch instead of some other caching method? A couple of reasons: +Why use a git branch instead of some other caching method? A couple of reasons: -- You can view and edit the cache contents right in the GitHub UI — no extra tooling needed. -- Everything is version-controlled, so you can manage it with the same git commands you already know. +- You can view and edit the cache contents right in the GitHub UI — no extra + tooling needed. +- Everything is version-controlled, so you can manage it with the same git + commands you already know. + +### How do I remove or reset the cache? + +Since the cache lives on the `gh-cache` branch, you have a couple of options: + +- **Delete the branch entirely** — the Action will create a fresh one on its + next run +- **Edit or remove specific files** on the branch through the GitHub UI or git + commands + +Just keep in mind that resetting the cache means the Action will "forget" what +it's already seen, so it may reopen issues that were previously tracked or +closed. ### Does this work with private repositories? -Yes! The Action works with both public and private repositories. Since it runs within GitHub Actions, it has access to your repository's content regardless of visibility settings. No extra configuration needed. +Yes! The Action works with both public and private repositories. Since it runs +within GitHub Actions, it has access to your repository's content regardless of +visibility settings. No extra configuration needed. ### Does this work with monorepos or multiple sites? -It does. If your repository contains multiple sites or projects, you can configure separate workflow runs targeting different URLs or paths. Each scan runs independently, so you can tailor the setup to match however your repo is structured. +It does. If your repository contains multiple sites or projects, you can +configure separate workflow runs targeting different URLs or paths. Each scan +runs independently, so you can tailor the setup to match however your repo is +structured. ### How often does / should the Action run? That's really up to you and your workflow. Some common setups include: -- **On every push or pull request** — great for catching issues early in development -- **On a scheduled cron job** (e.g., daily or weekly) — good for ongoing monitoring of live sites +- **On every push or pull request** — great for catching issues early in + development +- **On a scheduled cron job** (e.g., daily or weekly) — good for ongoing + monitoring of live sites - **Manually triggered** — useful for one-off audits -If you're just getting started, running on pull requests is a solid default — it catches problems before they get merged without adding noise to every single commit. +If you're just getting started, running on pull requests is a solid default — it +catches problems before they get merged without adding noise to every single +commit. ### Will this slow down my CI/CD pipeline? -The Action runs as its own job, so it won't block your builds or deployments unless you specifically configure it to. Scan times depend on the size and complexity of the site being scanned, but for most projects it adds minimal overhead. You can also run it on a schedule instead of on every push if speed is a concern. +The Action runs as its own job, so it won't block your builds or deployments +unless you specifically configure it to. Scan times depend on the size and +complexity of the site being scanned, but for most projects it adds minimal +overhead. You can also run it on a schedule instead of on every push if speed is +a concern. ### Can I customize which rules or checks are run? -Under the hood, this Action uses **[axe-core](https://github.com/dequelabs/axe-core)** — the industry gold standard for automated accessibility testing. That gives you a solid, well-maintained foundation right out of the box. +Under the hood, this Action uses +**[axe-core](https://github.com/dequelabs/axe-core)** — the industry gold +standard for automated accessibility testing. That gives you a solid, +well-maintained foundation right out of the box. -That said, you're not locked into a single setup. You can tap into different APIs and configure the Action to focus on the specific accessibility standards or rules that matter most to your project. +That said, you're not locked into a single setup. You can tap into different +APIs and configure the Action to focus on the specific accessibility standards +or rules that matter most to your project. -If you're looking to go even further, we also have resources for integrating accessibility into your development workflow with GitHub Copilot: +If you're looking to go even further, we also have resources for integrating +accessibility into your development workflow with GitHub Copilot: -- **[Getting Started with GitHub Copilot Custom Agents for Accessibility](https://accessibility.github.com/documentation/guide/getting-started-with-agents/)** — learn how to set up custom agents tailored to accessibility workflows -- **[Optimizing GitHub Copilot for Accessibility with Custom Instructions](https://accessibility.github.com/documentation/guide/copilot-instructions/)** — fine-tune how Copilot assists you with accessibility-specific guidance +- **[Getting Started with GitHub Copilot Custom Agents for + Accessibility](https://accessibility.github.com/documentation/guide/getting-started-with-agents/)** + — learn how to set up custom agents tailored to accessibility workflows +- **[Optimizing GitHub Copilot for Accessibility with Custom + Instructions](https://accessibility.github.com/documentation/guide/copilot-instructions/)** + — fine-tune how Copilot assists you with accessibility-specific guidance -Between axe-core's rule set, API flexibility, and Copilot's custom instructions, you've got a lot of room to shape the tooling around how your team actually works. +Between axe-core's rule set, API flexibility, and Copilot's custom instructions, +you've got a lot of room to shape the tooling around how your team actually +works. ### Does this work with GitHub Enterprise? -Yes, the Action is compatible with GitHub Enterprise Cloud. For GitHub Enterprise Server, compatibility may depend on your version and Actions availability. If you run into any issues, feel free to open an issue and we'll do our best to help. - -### How do I remove or reset the cache? - -Since the cache lives on the `gh-cache` branch, you have a couple of options: - -- **Delete the branch entirely** — the Action will create a fresh one on its next run -- **Edit or remove specific files** on the branch through the GitHub UI or git commands - -Just keep in mind that resetting the cache means the Action will "forget" what it's already seen, so it may reopen issues that were previously tracked or closed. +Yes, the Action is compatible with GitHub Enterprise Cloud. For GitHub +Enterprise Server, compatibility may depend on your version and Actions +availability. If you run into any issues, feel free to open an issue and we'll +do our best to help. ### Can multiple people use this on the same repo? -Absolutely. The Action is tied to the repository, not to any individual user. Anyone with the appropriate permissions can trigger runs, view results, and manage the issues it creates. It works just like any other GitHub Action in that regard. +Absolutely. The Action is tied to the repository, not to any individual user. +Anyone with the appropriate permissions can trigger runs, view results, and +manage the issues it creates. It works just like any other GitHub Action in that +regard. From 9c319b789f4d463fa3243357f69caf990fdd6215 Mon Sep 17 00:00:00 2001 From: Joyce Zhu Date: Fri, 27 Feb 2026 14:53:39 -0500 Subject: [PATCH 5/5] Update FAQ.md Co-authored-by: Helen Hou-Sandi --- FAQ.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FAQ.md b/FAQ.md index 44e6397..2fc4016 100644 --- a/FAQ.md +++ b/FAQ.md @@ -32,7 +32,7 @@ your users, that's exactly what we're here for. ### What's the `gh-cache` branch/Action all about? **The short version:** It's an orphan branch we use to store data between Action -runs. You can safely ignore it — it's just a behind-the-scenes detail. +runs. You can safely ignore it and any prompts to use it for a pull request — it's just a behind-the-scenes detail. **The longer version:** We use the `gh-cache` branch (and its associated Action) to keep track of issue data across runs. This is what prevents the Action from