GitHub Actions
Automatically scan every pull request and block merges when new accessibility violations are introduced — before they ever reach production.
Prerequisites
- An Aulys account (free or paid)
- An API key — generate one at app.aulys.app → Settings → API Keys
- A GitHub repository with Actions enabled
- A staging or preview URL that GitHub Actions can reach
Add your API key as a GitHub Secret
Never hard-code your API key. Store it as an encrypted GitHub secret so it's available to Actions without being visible in your code.
- 1. Go to your GitHub repository → Settings → Secrets and variables → Actions
- 2. Click New repository secret
- 3. Name it
AULYS_API_KEY - 4. Paste your API key from the Aulys dashboard and click Add secret
Create the workflow file
Create .github/workflows/accessibility.yml in your repository:
name: Accessibility Check
on:
pull_request:
branches: [main, staging]
jobs:
accessibility:
name: Aulys Scan
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run Aulys Accessibility Scan
uses: aulys-app/scan-action@v2
with:
# Your API key stored as a GitHub secret
api-key: ${{ secrets.AULYS_API_KEY }}
# URL to scan — typically your preview/staging deployment
url: https://staging.example.com
# Fail the check if any Critical violations are found
# Options: critical | warning | any | none
fail-on: critical
# WCAG level: A | AA | AAA
wcag-level: AA
# WCAG version: 2.1 | 2.2
wcag-version: "2.2"
# Post a PR comment with the violation summary
post-comment: trueAdvanced: scan multiple pages
To scan multiple URLs in a single run, use the urls input instead of url:
- name: Run Aulys Multi-Page Scan
uses: aulys-app/scan-action@v2
with:
api-key: ${{ secrets.AULYS_API_KEY }}
fail-on: critical
urls: |
https://staging.example.com/
https://staging.example.com/pricing
https://staging.example.com/contact
https://staging.example.com/blogWith Vercel preview deployments
If you use Vercel, you can wait for the preview URL to be ready and then scan it automatically:
jobs:
accessibility:
runs-on: ubuntu-latest
needs: [vercel-preview] # wait for preview to deploy
steps:
- name: Get preview URL
id: preview
run: echo "url=${{ needs.vercel-preview.outputs.preview-url }}" >> $GITHUB_OUTPUT
- name: Run Aulys Scan on Preview
uses: aulys-app/scan-action@v2
with:
api-key: ${{ secrets.AULYS_API_KEY }}
url: ${{ steps.preview.outputs.url }}
fail-on: critical
post-comment: trueFull input reference
| Input | Required | Default | Description |
|---|---|---|---|
api-key | Yes | — | Your Aulys API key |
url | Yes* | — | Single URL to scan. Use urls for multiple. |
urls | Yes* | — | Newline-separated list of URLs to scan. |
fail-on | No | critical | Severity level that causes the step to fail: critical | warning | any | none |
wcag-level | No | AA | WCAG conformance level: A | AA | AAA |
wcag-version | No | "2.2" | WCAG version: "2.1" or "2.2" |
post-comment | No | true | Post a PR comment with violation summary |
timeout | No | 60 | Scan timeout in seconds per page |
* Either url or urls is required, not both.
Troubleshooting
Action fails with "Unauthorized"
Check that AULYS_API_KEY is set correctly in GitHub Secrets and has not expired. Generate a new key in the Aulys dashboard if needed.
Scan times out
Increase the timeout input (e.g. timeout: 120). Pages with heavy JavaScript can take longer to render before Aulys can inspect the DOM.
Action fails but violations are only warnings
Change fail-on: warning to fail-on: critical to only block on the most severe issues while you remediate warnings over time.
Preview URL is not reachable from GitHub Actions
If your staging environment is behind a VPN or authentication, use the Aulys API directly from a self-hosted runner that has access, or whitelist GitHub Actions IP ranges in your firewall.