Axe DevTools Linter gebruiken met Bitbucket Pipelines

U kunt uw code indienen bij Axe DevTools Linter om te controleren op toegankelijkheidsproblemen als onderdeel van een Bitbucket Pipelines-build. In tegenstelling tot GitHub is er geen speciale Bitbucket-pipe voor Axe DevTools Linter, dus deze gids laat zien hoe u de Axe DevTools Linter Connector direct als een stap in uw bitbucket-pipelines.yml kunt aanroepen.

Vereisten

• Een Bitbucket-repository met ingeschakelde Pipelines.
• Node.js en npm beschikbaar in de pipeline-afbeelding (de standaard Bitbucket Pipelines-afbeelding bevat beide) zodat de Connector kan worden geïnstalleerd met npm. Zie De Axe DevTools Linter Connector installeren als een npm-pakket.
• Een API-sleutel of een licentiesleutel om de Connector te autoriseren. Zie De juiste installatie kiezen voor hoe uw implementatiemodel (SaaS, private cloud of on-premises) bepaalt welke u gebruikt.

Stap 1: Voeg een repository-variabele toe voor uw sleutel

Voeg uw sleutel toe als een beveiligde repository-variabele zodat deze niet wordt blootgesteld in uw pipeline-logboeken. Ga naar de Repository-instellingen-pagina van uw repository, vervolgens naar Repository-variabelen, en voeg een van de volgende opties toe, gemarkeerd met Beveiligd:

• AXE_LINTER_API_KEY voor een API-sleutel
• AXE_LINTER_LICENSE_KEY voor een licentiesleutel

Zie de eigen documentatie van Bitbucket over repository-variabelen en geheimen voor meer informatie.

Stap 2: Voeg een pipeline-stap toe

Voeg een stap toe aan uw bitbucket-pipelines.yml die de Connector installeert en deze uitvoert met de --local-optie. Lokaal linten analyseert uw bestanden op de eigen runner van de pipeline in plaats van ze naar een server te sturen, dus het werkt op dezelfde manier ongeacht of uw onderliggende implementatie SaaS, private cloud of on-premises is.

Met een licentiesleutel

Het gebruik van een licentiesleutel betekent dat de Connector helemaal geen netwerkoproepen doet:

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

Met een API-sleutel

Zelfs met --local vereist het gebruik van een API-sleutel nog steeds dat de Connector een authenticatieserver bereikt om de sleutel te valideren en gebruik te registreren.

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

Voor Axe DevTools Linter SaaS wordt de standaard authenticatieserver (https://axe.deque.com) automatisch gebruikt. Private cloud-klanten moeten de AXE_SERVICE_URL-omgevingsvariabele instellen op de authenticatie-URL van hun private cloud-instantie voordat ze de Connector uitvoeren.

Servergebaseerd linten (alternatief)

Als u niet lokaal wilt linten, kunt u in plaats daarvan bestanden naar een Axe DevTools Linter-server sturen door --local weg te laten en --url op te geven. Welke server u kunt bereiken, hangt af van uw implementatiemodel:

• SaaS: de gehoste runners van Bitbucket kunnen zonder extra setup de SaaS-server van Deque bereiken, aangezien deze al via het internet bereikbaar is.
• On-premises: stel uw on-prem server niet bloot aan het internet alleen zodat de gehoste runners van Bitbucket hem kunnen bereiken. Gebruik in plaats daarvan een Bitbucket zelfgehoste runner zodat uw pipeline-stap binnen uw eigen netwerk wordt uitgevoerd, dezelfde manier waarop uw on-prem server door andere interne tooling wordt bereikt.

Resultaten van de pipeline-stap

De Connector schrijft een toegankelijkheidsrapport naar de doeldirectory (standaard axe-linter-report.json), met daarin de specifieke gevonden toegankelijkheidsfouten, inclusief bestandsnaam en regelnummer. Toegankelijkheidsovertredingen veranderen op zichzelf de exitcode van de Connector niet en laten de Bitbucket-stap niet mislukken; de Connector verlaat alleen non-zero bij een probleem met de scan zelf, zoals een ontbrekende optie, een onbereikbare server of een geweigerde sleutel. Zie Exitcodes voor de volledige lijst.

Volgende stappen

Voor informatie over de regels die door Axe DevTools Linter worden gebruikt om uw code te controleren, zie Toegankelijkheidsregels. Als u het rapport wilt invoeren in SonarQube, zie Axe DevTools Linter gebruiken met SonarQube.