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 bij Een Axe DevTools Linter SaaS API-sleutel verkrijgen te volgen, of je kunt een bestaande API-sleutel van de instellingenpagina voor je Axe-account gebruiken. Als je problemen hebt met 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 maken om je bestanden op toegankelijkheidsfouten te controleren. Je kunt een bestand genaamd axe-linter.yml maken in de .github/workflows-map van je repo.

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 het lokaal maken en in je repo plaatsen.

De axe-linter-action wordt in de workflow opgeroepen wanneer een pull request wordt gemaakt (on: [pull_request]). De workflow gebruikt 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 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 gelezen vanuit de shellomgeving 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

Beginnend met v2.0.0, gebruikt axe-linter-action 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 automatisch je vastgezette SHA 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 schermafbeelding toont het resultaat van het aanmaken van een pull request met een bestand dat een toegankelijkheidsfout bevat. Het bestand, bad-file.md, bevat kopniveaus die van kopniveau 1 naar kopniveau 3 gaan, waarbij niveau 2 wordt overgeslagen, 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 machtigingen onjuist kunnen zijn. Als je bijvoorbeeld naar een repo verwijst die niet openbaar is met een uses-clausule, krijg je vaak de foutmelding dat de repo niet gevonden is in plaats van dat je er geen toegang toe hebt:

fatal: repository 'name' not found

Error: Resource not accessible by integration

Als je workflow niet kan worden uitgevoerd met de foutmelding, Resource not accessible by integration, kun je de volgende machtigingen aan je workflow toevoegen om dit te verhelpen:

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 Axe DevTools Linter gebruikt om je code te controleren, zie Toegankelijkheidsregels. Als je meer wilt weten over hoe je kunt voorkomen dat bestanden met toegankelijkheidsfouten naar Git worden gecomiteerd, zie Een Git Pre-Commit Hook Gebruiken.