De Axe DevTools Linter GitHub Actie Gebruiken

Dit artikel laat je zien hoe je de Axe DevTools Linter GitHub-actie van Deque kunt gebruiken om je code te controleren op toegankelijkheidsfouten bij het maken van een GitHub pull-aanvraag. Nadat de actie is uitgevoerd, zal de pull-aanvraag opmerkingen bevatten met de toegankelijkheidsfouten in de vastgelegde bestanden.

De volgende secties tonen de stappen voor het instellen van deze GitHub-actie met je repo.

Stap 1: Verkrijg een API-sleutel (Alleen SaaS)

Voor Axe DevTools Linter SaaS moet je een API-sleutel verkrijgen. Je kunt er een krijgen door de stappen te volgen op Een Axe DevTools Linter SaaS API-sleutel verkrijgen, of je kunt een bestaande API-sleutel gebruiken van de instellingenpagina voor je Axe-account. Als je problemen ondervindt bij het verkrijgen van een API-sleutel, neem dan contact op met Deques helpdesk.

Stap 2: Maak een Repository Secret voor je API-sleutel (Alleen SaaS)

Als je Axe DevTools Linter SaaS gebruikt, moet je je API-sleutel toevoegen aan de geheimen van je repository, wat je kunt doen door naar de Instellingen pagina van je repo op GitHub te gaan. Voor meer informatie, zie Versleutelde geheimen maken voor een repository op GitHub Docs.

Voor de voorbeeldworkflow in de volgende stap, zouden de geheimen als volgt moeten worden genoemd:

• AXE_LINTER_API_KEY voor de API-sleutel

Stap 3: Maak de Workflow

Vervolgens moet je een workflow creëren om je bestanden te controleren op toegankelijkheidsfouten. Je kunt een bestand met de naam axe-linter.yml in de map van je repo aanmaken .github/workflows directory.

Je kunt dit bestand online maken als een nieuwe workflow onder het tabblad Acties op de webpagina van je repo (klik op stel zelf een workflow in onder de sectie Aan de slag met GitHub Actions bovenaan de Acties pagina) of maak het lokaal en commit het naar je repo.

De axe-linter-action wordt aangeroepen in de workflow wanneer een pull-aanvraag wordt aangemaakt (on: [pull_request]). De workflow maakt gebruik van twee afhankelijkheden:

• actions/checkout@v4
• dequelabs/axe-linter-action@v2.0.0

De volgende secties tonen voorbeelden van .github/workflows/axe-linter.yml die je kunt gebruiken voor SaaS- of on-prem-versies van de Axe DevTools Linter:

Voor SaaS

De SaaS-versie van de workflow bevat de api_key parameter maar bevat niet de axe_linter_url parameter:

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v2.0.0
        with:
          api_key: ${{ secrets.AXE_LINTER_API_KEY }}          github_token: ${{ secrets.GITHUB_TOKEN }}

Voor On-Prem

De on-prem versie van de workflow bevat de axe_linter_url parameter maar bevat niet de api_key parameter:

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v2.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          axe_linter_url: $AXE_LINTER_URL

De waarde voor axe_linter_url wordt in dit voorbeeld uit de shell-omgeving gelezen als AXE_LINTER_URL.

Voor de on-premises versie van Axe DevTools Linter heeft u geen API-sleutel nodig, maar uw instantie van Axe DevTools Linter moet via een netwerkverbinding bereikbaar zijn voor GitHub-workflows.

Vastpinnen op een Commit SHA

Vanaf v2.0.0, axe-linter-action maakt gebruik van GitHub Immutable Releases. Dit betekent dat @v2.0.0 niet stilletjes kan worden omgeleid naar andere code nadat het is gepubliceerd.

Voor extra diepteverdediging kan je vastpinnen op de volledige commit SHA in plaats van op de versie-tag. Dit betekent dat zelfs als de tag-infrastructuur ooit zou worden omzeild, je workflow precies naar de commit blijft verwijzen die je oorspronkelijk hebt beoordeeld:

- uses: dequelabs/axe-linter-action@67f0f5c49a4171cb9171213a2e2ae877386b9a80 # v2.0.0

Je kunt de commit SHA voor elke versie vinden op de axe-linter-action releasepagina. Je kunt Dependabot gebruiken om je vastgepinde SHA automatisch up-to-date te houden. Voor meer informatie, zie Beveiligingsversterking voor GitHub Actions op GitHub Docs.

GitHub Action Parameters

De dequelabs/axe-linter-action gebruikt de volgende parameters (gespecificeerd in de bovenstaande voorbeelden in de with clausule):

Resultaten van de Workflow

De volgende screenshot toont het resultaat van het aanmaken van een pull-verzoek met een bestand dat een toegankelijkheidsfout bevat. Het bestand, bad-file.md, bevat kopniveaus die gaan van kopniveau 1 naar kopniveau 3 en kopniveau 2 overslaan, wat een toegankelijkheidsfout is.

Probleemoplossing

Fouten oplossen met GitHub-acties kan uitdagend zijn omdat de foutmeldingen vaak het onderliggende probleem niet nauwkeurig weergeven. Dit gedeelte bevat enkele voorbeelden van fouten die u kunt tegenkomen.

Onjuist Genaamd Geheim (Alleen SaaS)

Als de naam die u uw API-sleutelgeheim geeft niet overeenkomt met de naam in de workflow, kunt u fouten ontvangen over een ontbrekend commando in plaats van een fout dat het sleutel niet is gedefinieerd:

... line 41: Missing: command not found

Toestemmingsfouten

Er zijn veel plaatsen met GitHub-acties waar toestemmingen onjuist kunnen zijn. Bijvoorbeeld, als u verwijst naar een repo die niet openbaar is met een uses clausule, ontvangt u vaak de foutmelding dat de repo niet is gevonden in plaats van dat u er geen toegang toe heeft:

fatal: repository 'name' not found

Error: Resource not accessible by integration

Als uw workflow niet wordt uitgevoerd met de fout, Resource not accessible by integration, kunt u de volgende toestemmingen aan uw workflow toevoegen om dit op te lossen:

permissions:
  contents: read
  pull-requests: read 

Uw volledige workflow zou er dan als volgt uitzien:

on: [pull_request]

permissions:
  contents: read
  pull-requests: read

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v2.0.0
        with:
          api_key: ${{ secrets.AXE_LINTER_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

Bestanden Gecontroleerd door de Actie

Bestanden met deze extensies worden gecontroleerd op toegankelijkheidsfouten:

• .js
• .jsx
• .tsx
• .html
• .vue
• .md
• .markdown
• .liquid

Beperkingen

Bestandsaantal

Bij pull request-events scant de actie alle gewijzigde bestanden. Bij push-events beperkt de GitHub API de lijst van gewijzigde bestanden tot 300. Als een push meer dan 300 gewijzigde bestanden bevat, registreert de actie een waarschuwing om aan te geven dat sommige bestanden niet zijn gescand.

Bestandsgrootte

Bestanden groter dan ongeveer 900 kilobytes (900.000 bytes) worden overgeslagen en als waarschuwing geregistreerd. De Axe DevTools Linter API heeft een limiet van 1 MB voor de aanvraaggrootte. Oversized bestanden worden eruit gefilterd om aanvraagfouten te voorkomen.

Volgende Stappen

Voor informatie over de regels die door Axe DevTools Linter worden gebruikt om uw code te controleren, zie Toegankelijkheidsregels. Als u meer wilt weten over het voorkomen dat bestanden met toegankelijkheidsfouten in Git worden gecommit, zie Een Git Pre-Commit Hook Gebruiken.