Skip to content

Latest process updates #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 27, 2025
+92 −52
Merged

Latest process updates #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a64314c
Refine README for GitHub Copilot references
cehfisher Oct 23, 2025
f1100d7
Revise contributing guidelines for clarity and detail
cehfisher Oct 23, 2025
6d77d7e
Revise support guidelines and maintenance status
cehfisher Oct 23, 2025
eb704a7
Merge branch 'main' into latest-process-updates
cehfisher Oct 23, 2025
426f48f
Apply suggestions from code review
cehfisher Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 20 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Contributing
# Contributing

[fork]: https://github.com/github/accessibility-scanner/fork
[pr]: https://github.com/github/accessibility-scanner/compare
Expand All @@ -9,13 +9,29 @@ Contributions to this project are [released](https://help.github.com/articles/gi

Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

## Submitting a pull request
## How you can contribute

Thank you for your interest in this GitHub action, however, right now we are not taking contributions.
We are not accepting pull requests at this time. However, we welcome and encourage you to:

- **Test the a11y scanner** and share your experiences
- **Create issues** to report bugs, unexpected behavior, or documentation improvements
- **Share feedback** about your use cases and workflows

### Creating issues

When creating an issue, please provide:

- A clear and descriptive title
- Detailed steps to reproduce (for bugs)
- Expected vs. actual behavior
- Your environment details (OS, browser, GitHub Actions runner, etc.)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Your environment details (OS, browser, GitHub Actions runner, etc.)
- Your workflow file (with sensitive data removed)
- Your environment details (OS, browser, GitHub Actions runner, etc.)

- Any relevant logs or screenshots

### Feature requests

While we welcome feature requests, please note that we cannot guarantee that any feature request will be implemented or prioritized. We review all suggestions and consider them as part of our ongoing development process.

## Resources

- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
- [GitHub Support](https://support.github.com)
106 changes: 64 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,36 @@
# AI-powered Accessibility Scanner

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.
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 Copilot
- 🤖 Propose fixes with Copilot, with humans reviewing before merging
- 📝 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 beta. It can help identify accessibility gaps but cannot guarantee fully accessible code suggestions. Always review 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](https://youtu.be/CvRJcEzCSQM)** to see the a11y scanner in action.

---

## Requirements

This project is a GitHub Actions action. A GitHub Actions workflow is required to run it, and you must have available GitHub Actions minutes.
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
Copy link
Collaborator

@smockle smockle Oct 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role:

Suggested change
- **Admin access** to add repository secrets
- **Write access** (or higher) 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.

📚 [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions) | [Quickstart for GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) | [Writing workflows](https://docs.github.com/en/actions/how-tos/write-workflows) | [GitHub Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions)
## Getting Started
## Getting started

### 1. Add a Workflow File
### 1. Add a workflow file

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

```YAML
```yaml
name: Accessibility Scanner
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.

Expand All @@ -36,49 +43,64 @@ jobs:
urls: | # Provide a newline-delimited list of URLs to scan; more information below.
REPLACE_THIS
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.
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.
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.
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 all `REPLACE_THIS` placeholders with your actual values. See [Action Inputs](#action-inputs) for details.

Required Permissions:
**Required permissions:**

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

📚 [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions) | [Managing GitHub Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) | [Writing workflows](https://docs.github.com/en/actions/how-tos/write-workflows)
📚 Learn more
- [Quickstart for GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart)
- [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions)
- [Writing workflows](https://docs.github.com/en/actions/how-tos/write-workflows)
- [Managing GitHub Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository)
- [GitHub Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions)

---

### 2. Create a Token and Add a Secret
### 2. Create a token and add a secret

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

#### The `GH_TOKEN` is a fine-grained PAT with
**The `GH_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
- **Scope:** Your target repository (where issues and PRs will be created) and the repository containing your workflow

> 👉 GitHub Actions' default `GITHUB_TOKEN` cannot be used here.
> 👉 GitHub Actions' default [GITHUB_TOKEN](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) cannot be used here.

📚 [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)
📚 Learn more
- [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)

---

### 3. Run Your First Scan
### 3. Run your first scan

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.
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.

📚 [Running a workflow manually](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#running-a-workflow)
📚 Learn more
- [View workflow run history](https://docs.github.com/en/actions/how-tos/monitor-workflows/view-workflow-run-history)
- [Running a workflow manually](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#running-a-workflow)
- [Re-run workflows and jobs](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs)

---

## Action Inputs
## Action inputs

| Input | Required | Description | Example |
|-------|----------|-------------|---------|
Expand All @@ -88,54 +110,54 @@ Trigger the workflow manually or automatically based on your configuration. The
| `cache_key` | Yes | Key for caching results across runs<br>Allowed: `A-Za-z0-9._/-` | `cached_results-primer.style-main.json` |
| `login_url` | No | If scanned pages require authentication, the URL of the login page | `https://github.com/login` |
| `username` | No | If scanned pages require authentication, the username to use for login | `some-user` |
| `password` | No | If scanned pages require authentication, the password to use for login | `correct-horse-battery-staple` |
| `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"}}}` |
| `skip_copilot_assignment` | No | Whether to skip assigning filed issues to Copilot | `true` |
| `password` | No | If scanned pages require authentication, the password to use for login | `${{ secrets.PASSWORD }}` |
| `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":[...]}` |
| `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` |

---

## Authentication

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.

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.)
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.)

> [!IMPORTANT]
> 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).
> 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).

---

## Configuring Copilot
## Configuring GitHub Copilot

The a11y scanner leverages Copilot coding agent, which can be configured with custom instructions:
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`
- **Repository-wide:** `.github/copilot-instructions.md`
- **Directory/file-scoped:** `.github/instructions/*.instructions.md`

📚 [Adding repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) | [Copilot .instructions.md support](https://github.blog/changelog/2025-07-23-github-copilot-coding-agent-now-supports-instructions-md-custom-instructions/) | [Copilot agents.md support](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions) | [Optimizing GitHub Copilot for accessibility](https://accessibility.github.com/documentation/guide/copilot-instructions)
📚 Learn more
- [Adding repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
- [Optimizing GitHub Copilot for accessibility](https://accessibility.github.com/documentation/guide/copilot-instructions)
- [GitHub Copilot .instructions.md support](https://github.blog/changelog/2025-07-23-github-copilot-coding-agent-now-supports-instructions-md-custom-instructions/)
- [GitHub Copilot agents.md support](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions)

---

## Feedback

Please refer to the [CONTRIBUTING](./CONTRIBUTING.md) file for more information.
💬 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

This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.
📄 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

Please refer to the [CODEOWNERS](./.github/CODEOWNERS) file for more information.
🔧 Please refer to the [CODEOWNERS](./.github/CODEOWNERS) file for more information.

## Support

Please refer to the [SUPPORT](./SUPPORT.md) file for more information.
❓ Please refer to the [SUPPORT](./SUPPORT.md) file for more information.

## Acknowledgement

Thank you to our beta testers for their help in testing this project.

---

*Last updated: 2025-10-09*
✨ Thank you to our beta testers for their help with making this project!
14 changes: 8 additions & 6 deletions SUPPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
# Support

## How to file issues and get help
## How to get help

This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue.
This project uses GitHub Issues to track bugs, feature requests, and support inquiries. Please search the existing issues before filing new issues to avoid duplicates.

For help or questions about using this project, please open an issue for support requests, usage questions, or general inquiries. At this time, GitHub Discussions are not enabled. All communication should occur via issues.

## Project Maintenance Status
For information about contributing to this project, including how to create issues and what types of contributions we accept, please refer to the [CONTRIBUTING](./CONTRIBUTING.md) file.

## Project maintenance status

This repo `github/accessibility-scanner` is under active development and maintained by GitHub staff during the public preview state. We will do our best to respond to support, feature requests, and community questions in a timely manner.

## Important Notice
## Important notice

This project is a work in progress, and we do not guarantee that code fixes or suggestions produced by Copilot will be fully accessible. Please use caution when applying the suggestions it provides. Always confirm or verify Copilot's recommendations with an accessibility subject matter expert before using them in production.
The a11y scanner is currently in public preview and feature development work is still ongoing. This project cannot guarantee that code fixes or suggestions produced by GitHub Copilot will be fully accessible. Please use caution when applying the suggestions it provides. Always confirm or verify GitHub Copilot's recommendations with an accessibility subject matter expert before using them in production.

## GitHub Support Policy
## GitHub support policy

Support for this project is limited to the resources listed above (GitHub Issues).