Using Axe DevTools Linter with Bitbucket Pipelines

You can submit your code to Axe DevTools Linter to be checked for accessibility problems as part of a Bitbucket Pipelines build. Unlike GitHub, there's no dedicated Bitbucket pipe for Axe DevTools Linter, so this guide shows how to invoke the Axe DevTools Linter Connector directly as a step in your bitbucket-pipelines.yml.

Requirements

• A Bitbucket repository with Pipelines enabled.
• Node.js and npm available in the pipeline image (the default Bitbucket Pipelines image includes both) so the Connector can be installed with npm. See Installing the Axe DevTools Linter Connector as an npm package.
• An API key or a license key to authorize the Connector. See Choosing the Right Setup for how your deployment model (SaaS, private cloud, or on-premises) determines which one you use.

Step 1: Add a Repository Variable for Your Key

Add your key as a secured repository variable so it isn't exposed in your pipeline logs. Go to your repository's Repository settings page, then Repository variables, and add one of the following, marked Secured:

• AXE_LINTER_API_KEY for an API key
• AXE_LINTER_LICENSE_KEY for a license key

For more information, see Bitbucket's own documentation on repository variables and secrets.

Step 2: Add a Pipeline Step

Add a step to your bitbucket-pipelines.yml that installs the Connector and runs it with the --local option. Local linting analyzes your files on the pipeline's own runner instead of sending them to a server, so it works the same way regardless of whether your underlying deployment is SaaS, private cloud, or on-premises.

With a License Key

Using a license key means the Connector makes no network calls at all:

image: node:20

pipelines:
  default:
    - step:
        name: Lint for accessibility issues
        script:
          - npm install -g @axe-devtools/axe-linter-connector
          - axe-linter-connector -s . -d . --license-key $AXE_LINTER_LICENSE_KEY --local

With an API Key

Using an API key still requires the Connector to reach an authentication server to validate the key and record usage, even with --local:

image: node:20

pipelines:
  default:
    - step:
        name: Lint for accessibility issues
        script:
          - npm install -g @axe-devtools/axe-linter-connector
          - axe-linter-connector -s . -d . --api-key $AXE_LINTER_API_KEY --local

For Axe DevTools Linter SaaS, the default authentication server (https://axe.deque.com) is used automatically. Private cloud customers need to set the AXE_SERVICE_URL environment variable to their private cloud instance's authentication URL before running the Connector.

Server-Based Linting (Alternative)

If you don't want to lint locally, you can instead send files to an Axe DevTools Linter server by omitting --local and specifying --url. Which server you can reach depends on your deployment model:

• SaaS: Bitbucket's hosted runners can reach Deque's SaaS server with no extra setup, since it's already internet-reachable.
• On-premises: don't expose your on-prem server to the internet just so Bitbucket's hosted runners can reach it. Instead, use a Bitbucket self-hosted runner so your pipeline step runs inside your own network, the same way your on-prem server is reached by other internal tooling.

Results of the Pipeline Step

The Connector writes an accessibility report to the destination directory (axe-linter-report.json by default), containing the specific accessibility errors found, including filename and line number. Accessibility violations by themselves don't change the Connector's exit code or fail the Bitbucket step; the Connector only exits nonzero for a problem with the scan itself, such as a missing option, an unreachable server, or a rejected key. See Exit Codes for the complete list.

Next Steps

For information about the rules used by Axe DevTools Linter to check your code, see Accessibility Rules. If you'd like to feed the report into SonarQube, see Using Axe DevTools Linter with SonarQube.