Using the axe Developer Hub GitHub Action

This article describes how to set up the axe Developer Hub GitHub action, which automates using axe Developer Hub with GitHub. The action allows you to block commits and pull requests if they contain more accessibility errors than the a11y threshold (defaults to zero).

Prerequisites

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

1. You should have set up a project on axe Developer Hub and have its API key.
2. You need a test suite that you've modified by following the directions in axe Developer Hub when you create a new project.

See Get Started with axe Developer Hub for more information.

The following sections describe the steps necessary to set up a workflow that uses 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 created secret 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: Create a New (or Modify an Existing) Workflow

You need to create a new (or modify an existing) workflow in .github/workflows. You can use the example workflow as a starting point. (The example directory contains a complete test project you can experiment with.)

Example Workflow

The example workflow (mentioned above) is called Tests (tests.yml) and runs on any commit as shown by the configuration at the beginning of the workflow:

name: Tests

on: [push]

There are several jobs run in the example workflow upon push. The job that runs the test suite, cypress, will need to be modified for your test suite. However, if you already have a job that runs your test suite, it's unlikely that you will need to modify it; axe Developer Hub relies on a modified test suite (as detailed in the instructions when you created the project in axe Developer Hub) to do most of the analysis and reporting.

Step 3: Add the axe Developer Hub GitHub Action as a Job

The job following your test suite action should run the axe Developer Hub GitHub action. Your test suite job reports accessibility errors and Git info to axe Developer Hub, and the following job retrieves that information from axe Developer Hub.

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:

  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 }}

This job is dependent on the previous 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.

Several output parameters are also set. See Output Parameters for more information.

Troubleshooting

You might receive an error such as the following:

Error: Resource not accessible by integration

To fix this, 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.

Reference

See the axe Developer Hub README

See Also

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