Accessibility testing

Introduced in GitLab 12.8.

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

Version history

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 for GitLab 12.9 and later:

  1. Include the Accessibility.gitlab-ci.yml template from your GitLab installation.
  2. Add the following configuration to your .gitlab-ci.yml file.

    stages:
      - accessibility
    
    variables:
      a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in"
    
    include:
      - 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
For GitLab versions earlier than 12.9, use include:remote and link to the current template in the default branch
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.