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 en stelt api_key in op een placeholdwaarde:

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 }}
          api_key: on-prem-no-key-required          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 heb je geen API-sleutel nodig: je on-prem server is geautoriseerd met zijn eigen licentiecode en valideert de api_key waarde niet. Vanaf axe-linter-action v2.0.0 is api_key echter een vereiste invoer, dus je moet een niet-lege placeholdwaarde opgeven (zoals on-prem-no-key-required hierboven) anders mislukt de actie met Input required and not supplied: api_key. Je exemplaar van Axe DevTools Linter moet ook 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
• .esm
• .html
• .htm
• .vue
• .md
• .markdown
• .liquid

Bestanden met een andere extensie worden genegeerd, evenals bestanden die door de pull-aanvraag of push worden verwijderd en bestanden die leeg zijn (bestanden waarvan de inhoud alleen uit spaties bestaat).

De actie slaat ook elk bestand over waarvan het pad een segment bevat dat met een punt begint (.). Niets in mappen zoals .github of .storybook, en geen dotfiles, worden naar de linter gestuurd.

Beperkingen

Bestandsaantal

Vanaf axe-linter-action v2.0.0 voert de pull-aanvraag elke gewijzigd bestand in de pull-aanvraag uit met lint, ongeacht hoeveel bestanden de pull-aanvraag bevat. Eerdere versies vroegen alleen de eerste pagina van gewijzigde bestanden op via de GitHub API, wat elke run beperkte tot ongeveer de eerste 30 bestanden. Omdat die limiet stilzwijgend was, kon een pull-aanvraag de actie doorstaan, terwijl toegankelijkheidsfouten in de resterende bestanden onopgemerkt bleven. Als je nog steeds v1.x gebruikt, upgrade dan naar v2.0.0 zodat de hele pull-aanvraag wordt gelint.

Push-events werken anders: de actie vergelijkt twee commits, en de GitHub API retourneert maximaal 300 bestanden voor een vergelijking. Als een push meer dan 300 bestanden wijzigt, logt de actie een waarschuwing om aan te geven dat sommige bestanden niet zijn gescand. Het uitvoeren van de actie op pull_request-events, zoals de voorbeelden op deze pagina doen, is de manier om ervoor te zorgen dat elke gewijzigd bestand wordt gecontroleerd.

Pad-uitsluitingen

De actie heeft geen parameter om paden uit te sluiten. Elk gewijzigd bestand met een ondersteunde extensie wordt gelint, inclusief bestanden in vendordirectory's zoals een ingecheckt node_modules. Als je repository code van derden commit, kun je verwachten dat die bestanden worden gelint wanneer een pull-aanvraag ze wijzigt, wat ook bijdraagt aan de tijdsduur van de run.

Als je controle nodig hebt over precies welke paden worden gelint, gebruik dan de Axe DevTools Linter Connector, die je kunt aanwijzen naar welke bestanden of directories je maar wilt.

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.