Using the axe-linter GitHub Action

Link to Using the axe-linter GitHub Action copied to clipboard

How to use the axe-linter GitHub action to check pull requests for accessibility errors

This article shows you how to use Deque's axe-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 the axe-linter service. You can obtain one by following the steps here 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 .git/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 .git/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:

Name Description
github_token Required for authentication. Usually set by the predefined GITHUB_TOKEN secret. For more information, see Automatic Token Identification on GitHub Docs.
api_key This is the API key that is required to authorize your workflow with Deque's axe-linter SaaS. In the above example, the key is obtained from the AXE_LINTER_API_KEY secret you created.
axe_linter_url (Optional) This parameter lets you specify a different server to use for linting. Most users won't need to use this parameter because they'll use Deque's servers for linting. Because it's not a secret, you'll typically store it in the environment. You can find more information in Environment Variables

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.

A pull request on GitHub and the error flagged by the axe linter GitHub action. The file shown on the right side of the image contains an accessibility error where the headings skip level 2. There is an error alert from the GitHub action providing details about the 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 the axe-linter server 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.