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 creating 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 (SaaS Only)

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

Step 2: Create a Repository Secret for Your API Key (SaaS Only)

If you're using axe DevTools Linter SaaS, you need to add your API key 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 must create a workflow to check your files for accessibility errors. You can create a file named axe-linter.yml in your repo's .github/workflows directory.

You can create this file online as a new workflow under the Actions tab on your repo's webpage (click on set up a workflow yourself under the section Get started with GitHub Actions at the top of the Actions page) or create it locally and commit it to your repo.

The axe-linter action is invoked in the workflow when a pull request is created (on: [pull_request]). The workflow uses two dependencies:

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

The following sections show examples of .github/workflows/axe-linter.yml that you can use for SaaS or on-prem versions of axe DevTools Linter:

For SaaS

The SaaS version of the workflow includes the api_key parameter but does not include the axe_linter_url parameter:

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

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

For On-Prem

The on-prem version of the workflow includes the axe_linter_url parameter but does not include the api_key parameter:

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          axe_linter_url: $AXE_LINTER_URL

The value for axe_linter_url is read in this example from the shell environment as AXE_LINTER_URL.

For the on-premises version of axe DevTools Linter, you do not need an API key, but your instance of axe DevTools Linter must be reachable to GitHub workflows via a network connection.

GitHub Action Parameters

The dequelabs/axe-linter-action uses the following parameters (specified in the above samples in the with clause):

Results of the Workflow

The following screenshot 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 go from heading level 1 to heading level 3, skipping level 2, which is an accessibility error.

Troubleshooting

Debugging issues with GitHub actions can be challenging because the error messages often fail to represent the underlying problem accurately. This section contains some examples of errors you might see.

Incorrectly Named Secret (SaaS Only)

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 GitHub 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 to check your code, see Accessibility Rules. If you'd like to know more about preventing files with accessibility errors from being committed to Git, see Using a Git Pre-Commit-Hook.