Using the axe Developer Hub GitHub Action

This article tells how to set up the axe Developer Hub GitHub action, which allows GitHub workflows to block commits and pull requests if they contain any accessibility errors.

Overview

When your modified test suite runs, it associates accessibility results with a Git commit SHA and sends that information to Deque's servers. Later, when the GitHub action runs, it queries Deque for these results.

Requirements

There are a few requirements to satisfy before you can use the GitHub action:

1. A project on axe Developer Hub and its API key.
2. A test suite you've modified by following the instructions in axe Developer Hub when you created the project.
3. A GitHub workflow that runs your test suite whenever someone commits to your repo.

The following sections describe the steps necessary to modify a workflow to use the axe Developer Hub GitHub action.

Step 1: Create a Secret for Your API Key

See Encrypted Secrets in a Workflow for information on creating a secret for your workflow.

For this example, the secret created is called AXE_DEV_HUB_API_KEY, with your project's API key as its value, but you can name the secret whatever you want. It must be referenced by the same name in the workflow job.

Step 2: Modify Your Current Workflow

You need to modify your current test runner workflow in .github/workflows and add the GitHub action after the job that runs your test suite.

The job following your test suite action should run the axe Developer Hub GitHub action. Here is an example of a job that runs the axe Developer Hub GitHub action (the jobs: line is included to show where the action is in the workflow):

jobs:

# ...
# Job that runs your test suite (deleted for brevity)
# ...

# Add the following new job:

  axe-dev-hub:
    runs-on: ubuntu-latest
    needs: cypress
    steps:
      - uses: actions/checkout@v3
      - uses: dequelabs/axe-devhub-action@v1
        with:
          api_key: ${{ secrets.AXE_DEV_HUB_API_KEY }}

See the table of input parameters for all possible input parameters to the GitHub action. You can, for instance, enable the a11y threshold by using enable_a11y_threshold: true. (Always check the example invocation in the GitHub action repo for the latest job configuration. However, unlike in the example invocation, do not set the server_url parameter unless you use a test server, which is uncommon.)

This job depends on the job that runs your test suite, specified with the needs: cypress line. Be sure to update this line to match the name of the job that runs your test suite.

Results

If the GitHub action fails (more than zero accessibility errors), it attaches a comment similar to the following to your push request and blocks merging:

If you click on the link, you will be brought to the axe Developer Hub page that displays accessibility defect information for that commit.

The GitHub action sets several output parameters. See the table of output parameters for more information.

Troubleshooting

You might receive an error such as the following:

Error: Resource not accessible by integration

To fix this error, you need read and write permissions for actions (to allow the action to add comments to pull requests), either in the settings page for actions or, for more granularity, via a different GITHUB_TOKEN. See Modifying the permissions for the GITHUB_TOKEN for more information. You can use the input value github_token to specify a different token to the GitHub action.

Example Workflow

The axe Developer Hub GitHub action's repository contains an example workflow that you can use to create your own test runner. The example workflow is called Tests (tests.yml) and runs on any commit or pull request.

The job that runs the modified test suite, cypress, shows how to run a Cypress test suite. The following job, axe-dev-hub, is an example invocation of the axe Developer Hub GitHub action. Your test suite job should always run before the axe Developer Hub GitHub action.

Reference

See the axe Developer Hub README for information about the input and output parameters for the GitHub action.

See Also

• axe Developer Hub GitHub Action repo
• action.yml
• Example test suite