Using the Axe Developer Hub GitHub Action

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Automatically check PRs and commits for accessibility defects

Not for use with personal data

Requires:

A web project with Axe Watcher integration

Axe Developer Hub Project ID

Axe Developer Hub API Key

A test suite you've modified by following the setup instructions in Axe Developer Hub

A GitHub workflow that runs your test suite whenever someone commits to your repo

note

For other CI/CD pipelines (such as those on GitLab, Bitbucket, or CircleCI) or when using Axe DevTools for Web APIs/CLI, you can use the Axe Developer Hub REST service as the basis for your own integration.

Overview

The Axe Developer Hub GitHub Action allows you to set up GitHub workflows for web projects integrating Axe Watcher, to block commits and pull requests if they contain any accessibility errors.

When your modified test suite runs, it associates accessibility results with a Git commit SHA and sends that information to Deque's servers. The GitHub action runs after your test suite runs, and it queries Deque's servers for the accessibility results associated with the current branch's latest commit SHA.

Setup

Create an Environment Variable for Your Project ID - We recommend that you store your project ID in an environment variable or other GitHub variable. For this example, we'll store the project ID as an environment variable called PROJECT_ID.
Create a Secret for Your API Key - For this example, the secret created is called AXE_DEV_HUB_API_KEY, with your personal 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.
Add Accessibility Checks to Your Test Suite - Ensure that you have completed the steps in project setup to integrate accessibility checks in the test suite being used in your (Axe Watcher) CI/CD pipeline.
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.

Example Job

The job following your test suite action should run the Axe Developer Hub GitHub action. Refer to the following example:

jobs:

# ...
# your-CI-test
# ...

# Add the following new job:
# Be sure to replace <choose_latest_tag> with the appropriate version tag
  axe-dev-hub:
    runs-on: ubuntu-latest
    needs: your-CI-test
    steps:
      - uses: actions/checkout@v5
      - uses: dequelabs/axe-devhub-action@<choose_latest_tag>
        with:
          api_key: ${{ secrets.axe_DEV_HUB_API_KEY }}
          project_id: ${{ env.PROJECT_ID }}

The axe-dev-hub job in the example depends on the job that runs your test suite, specified with the needs: your-CI-test line. Be sure to update this line to match the name of the job that runs your test suite.

You can use multiple input parameters for the GitHub Action. For instance, you can enable the a11y threshold by using enable_a11y_threshold: true. A full list of input parameters can be found in the Axe Developer Hub GitHub Action README.

Note: You do not need to set the server_url parameter if you created your project on axe.deque.com. If you are using a different environment, you must set this to match the URL your project was created on.

Results

The GitHub action sets several output parameters, including a count of accessibility issues that were detected, issues that were resolved, and issues surpassing the a11y threshold.

If you have not enabled the a11y threshold, the GitHub Action will fail whenever more than zero accessibility errors are present. If enabled, only violations surpassing the a11y threshold will cause the GitHub Action to fail. Learn more about using the a11y threshold to customize Axe Developer Hub for what your organization wishes to prioritize.

Failure of the GitHub Action will attach a comment similar to the one below to your pull request and can block merging.

Click the link in the pull request comment to review accessibility defect information for that commit in Axe Developer Hub.

Troubleshooting

You might receive an error such as the following:

Error: Resource not accessible by integration

Check that you have the necessary permissions in the settings page for actions. You need read and write permissions to allow the action to add comments to pull requests. For more granularity, you may opt to use a different GITHUB_TOKEN for the GitHub action. Add this value to the github_token input parameter.

Example Workflow

If you don't already have a workflow that runs your test suite, you can use the example workflow as a starting point 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 in the example, axe-dev-hub, is an invocation of the Axe Developer Hub GitHub action.

Your test suite job should always run before the Axe Developer Hub GitHub action.

tip

The example directory contains a complete test project you can experiment with.

References

Main repository for the Axe Developer Hub GitHub Action
- The README has information about the input and output parameters
- Find metadata for the GitHub Action in action.yml
- Check the example invocation in the GitHub action repo periodically for the latest job configuration
Find more info about topics on this page in GitHub's documentation