Using the axe DevTools Linter GitHub Action

This article shows you how to use Deque's axe DevTools Linter GitHub action to check your code for accessibility errors upon creation of a GitHub pull request. After the action is run, the pull request will contain comments showing the accessibility errors in the committed files.

The following sections show the steps for setting up this GitHub action with your repo.

Step 1: Obtain an API Key

You need to obtain an API key to use axe DevTools Linter SaaS. You can obtain one by following the steps at Obtaining an axe DevTools Linter SaaS API Key or you can use an existing API key by visiting the settings page for your axe account. If you have any problems obtaining an API key, contact Deque's help desk.

Step 2: Create a Repository Secret for Your API Key

After you've obtained an API key, you need to add it to your repository's secrets, which you can do by going to your repo's Setting page on GitHub. For more information, see Creating encrypted secrets for a repository on GitHub Docs.

For the example workflow in the next step, the secrets should be called:

• AXE_LINTER_API_KEY for the API key

Step 3: Create the Workflow

Next, you'll need to create a workflow to start checking your files for accessibility errors. You can create a file in your repo in the .github/workflows directory named axe-linter.yml.

You can create this file online as new action under the Actions tab on your repo's webpage. Or you can create it locally and commit it to your repo.

The following is an example of .github/workflows/axe-linter.yml that you can use:

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - uses: dequelabs/axe-linter-action@v1
        with:
          api_key: ${{ secrets.AXE_LINTER_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

This action is invoked when a pull request is created (on: [pull_request]). It uses two dependencies:

• actions/checkout@v3
• dequelabs/axe-linter-action@v1

The dequelabs/axe-linter-action uses three parameters (specified in the above sample in the with clause); two are required and one is optional:

Results of the Workflow

The following screen shot shows the result of creating a pull request with a file that has an accessibility error. The file, bad-file.md, contains heading levels that skip from heading level 1 to heading level 3, skipping level 2, which is an accessibility error.

Troubleshooting

Sometimes it is difficult to debug problems with GitHub actions because the error messages often don't reflect what the problem is. This section contains some examples of errors you might see.

Incorrectly Named Secret

If the name you give your API key secret doesn't match the name in the workflow, you can receive errors about a missing command rather than an error that the key isn't defined:

... line 41: Missing: command not found

Permissions Errors

There are many places with GigHub actions where permissions can be incorrect. For example, if you reference a repo that isn't public with a uses clause, you often will receive the error that the repo wasn't found instead of you don't have access to it:

fatal: repository 'name' not found

Files Checked by the Action

Files with these extensions will be checked for accessibility errors:

• .js
• .jsx
• .tsx
• .html
• .vue
• .md
• .markdown

Next Steps

For information about the rules used by axe DevTools Linter for checking your code, see Accessibility Rules. If you'd like to know more about preventing files with accessibility errors from being commited to Git, see Using a Git Pre-Commit-Hook.