Skip to content

Accessibility Testing

Introduced in GitLab 12.8.

If your application offers a web interface and you are using GitLab CI/CD, you can quickly determine the accessibility impact of pending code changes.

Overview

GitLab uses pa11y, a free and open source tool for measuring the accessibility of web sites, and has built a simple CI job template. This job outputs accessibility violations, warnings, and notices for each page analyzed to a file called accessibility.

Accessibility Merge Request widget

Since GitLab 13.0, in addition to the report artifact that is created, GitLab will also show the Accessibility Report in the merge request widget area:

Accessibility Merge Request Widget

This widget comes with the :accessibility_report_view feature flag disabled by default while we test feature stability. Once we have determined the widget is stable, this feature will be enabled by default.

To enable this feature, ask a GitLab administrator with Rails console access to run the following command:

Feature.enable(:accessibility_report_view)

Configure Accessibility Testing

This example shows how to run pa11y on your code with GitLab CI/CD using the GitLab Accessibility Docker image.

For GitLab 12.9 and later, to define the a11y job, you must include the Accessibility.gitlab-ci.yml template included with your GitLab installation, as shown below.

Add the following 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"

creates an a11y job in your CI/CD pipeline, runs Pa11y against the webpages defined in a11y_urls, and builds an HTML report for each.

The report for each URL is saved as an artifact that can be viewed directly in your browser.

A single gl-accessibility.json artifact is created and saved along with the individual HTML reports. It includes report data for all URLs scanned.

NOTE: Note: For GitLab 12.10 and earlier, the artifact generated is named accessibility.json.

NOTE: Note: For GitLab versions earlier than 12.9, you can use include:remote and use a link to the current template in master

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

It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything, copy the template to your CI file and make the desired edits.