Skip to content

Accessibility testing

DETAILS: Tier: Free, Premium, Ultimate Offering: SaaS, self-managed

If your application offers a web interface, you can use GitLab CI/CD to determine the accessibility impact of pending code changes.

Pa11y is a free and open source tool for measuring the accessibility of web sites. GitLab integrates Pa11y into a CI/CD job template. The a11y job analyzes a defined set of web pages and reports accessibility violations, warnings, and notices in a file named accessibility.

As of GitLab 14.5, Pa11y uses WCAG 2.1 rules.

Accessibility merge request widget

GitLab displays an Accessibility Report in the merge request widget area:

Accessibility merge request widget

Configure accessibility testing

You can run Pa11y with GitLab CI/CD using the GitLab Accessibility Docker image.

To define the a11y job:

  1. Include the Accessibility.gitlab-ci.yml template from your GitLab installation.

  2. Add the following configuration to your .gitlab-ci.yml file.

      - accessibility
      a11y_urls: ""
      - template: "Verify/Accessibility.gitlab-ci.yml"
  3. Customize the a11y_urls variable to list the URLs of the web pages to test with Pa11y.

The a11y job in your CI/CD pipeline generates these files:

  • One HTML report per URL listed in the a11y_urls variable.
  • One file containing the collected report data. In GitLab versions 12.11 and later, this file is named gl-accessibility.json. In GitLab versions 12.10 and earlier, this file is named accessibility.json.

You can view job artifacts in your browser.

NOTE: The job definition provided by the template does not support Kubernetes.

You cannot pass configurations into Pa11y via CI configuration. To change the configuration, edit a copy of the template in your CI file.