Verwendung der Axe DevTools Linter GitHub Action

Dieser Artikel zeigt Ihnen, wie Sie die Axe DevTools Linter GitHub Action von Deque verwenden, um Ihren Code auf Barrierefreiheitsfehler zu überprüfen, wenn ein GitHub-Pull-Request erstellt wird. Nachdem die Action ausgeführt wurde, enthält der Pull-Request Kommentare, die die Barrierefreiheitsfehler in den committed Dateien anzeigen.

Die folgenden Abschnitte zeigen die Schritte zum Einrichten dieser GitHub Action in Ihrem Repository.

Schritt 1: API-Schlüssel erhalten (Nur SaaS)

Für die SaaS-Version von Axe DevTools Linter benötigen Sie einen API-Schlüssel. Sie können einen erhalten, indem Sie den Schritten bei Einen API-Schlüssel für Axe DevTools Linter SaaS erhalten folgen, oder Sie können einen vorhandenen API-Schlüssel von der Einstellungsseite für Ihr Axe-Konto verwenden. Wenn Sie Probleme beim Erhalten eines API-Schlüssels haben, kontaktieren Sie den Deque Helpdesk.

Schritt 2: Ein Repository-Geheimnis für Ihren API-Schlüssel erstellen (Nur SaaS)

Wenn Sie Axe DevTools Linter SaaS verwenden, müssen Sie Ihren API-Schlüssel zu den Geheimnissen Ihres Repositories hinzufügen. Dies können Sie tun, indem Sie die Einstellungen-Seite Ihres Repos auf GitHub aufrufen. Weitere Informationen finden Sie unter Erstellen verschlüsselter Geheimnisse für ein Repository in den GitHub-Dokumentationen.

Für das Beispiel-Workflow im nächsten Schritt sollten die Geheimnisse folgendes genannt werden:

• AXE_LINTER_API_KEY für den API-Schlüssel

Schritt 3: Den Workflow erstellen

Als Nächstes müssen Sie einen Workflow erstellen, um Ihre Dateien auf Barrierefreiheitsfehler zu überprüfen. Sie können eine Datei mit dem Namen axe-linter.yml im .github/workflows-Verzeichnis Ihres Repos erstellen.

Sie können diese Datei online als neuen Workflow unter dem Actions-Tab auf der Webseite Ihres Repos erstellen (klicken Sie auf Richten Sie einen Workflow selbst ein im Abschnitt Erste Schritte mit GitHub Actions oben auf der Actions-Seite) oder lokal erstellen und in Ihr Repo commiten.

Der axe-linter-action wird im Workflow ausgelöst, wenn eine Pull-Anfrage erstellt wird (on: [pull_request]). Der Workflow verwendet zwei Abhängigkeiten:

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

In den folgenden Abschnitten werden Beispiele für .github/workflows/axe-linter.yml gezeigt, die Sie für SaaS- oder On-Prem-Versionen von Axe DevTools Linter verwenden können:

Für SaaS

Die SaaS-Version des Workflows enthält den api_key-Parameter, aber nicht den 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 }}

Für On-Prem

Die On-Prem-Version des Workflows beinhaltet den axe_linter_url-Parameter und setzt api_key auf einen Platzhalterwert:

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

Der Wert für axe_linter_url wird in diesem Beispiel aus der Shell-Umgebung als AXE_LINTER_URL gelesen.

Für die On-Premise-Version von Axe DevTools Linter benötigen Sie keinen API-Schlüssel: Ihr On-Prem-Server ist mit seinem eigenen Lizenzschlüssel autorisiert und validiert den api_key-Wert nicht. Ab axe-linter-action v2.0.0 ist jedoch api_key eine erforderliche Eingabe, sodass Sie einen nicht-leeren Platzhalterwert (wie on-prem-no-key-required oben) angeben müssen, oder die Aktion schlägt mit Input required and not supplied: api_key fehl. Ihre Instanz von Axe DevTools Linter muss außerdem über eine Netzwerkverbindung für GitHub Workflows erreichbar sein.

Festlegen auf ein Commit-SHA

Beginnend mit v2.0.0 verwendet axe-linter-action . Das bedeutet, dass. Dies bedeutet, dass @v2.0.0 nicht stillschweigend auf anderen Code umgeleitet werden kann, nachdem es veröffentlicht wurde.

Sie können das Commit-SHA für jede Version auf der

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

Den Commit-SHA für jede Version finden Sie im finden. Sie können. Sie können verwenden, um Ihr festgelegtes SHA automatisch auf dem neuesten Stand zu halten. Weitere Informationen finden Sie unter verwenden, um Ihren fixierten SHA automatisch auf dem neuesten Stand zu halten. Weitere Informationen finden Sie unter in den GitHub-Dokumentationen. in den GitHub-Dokumentationen.

Die

Der dequelabs/axe-linter-action verwendet die folgenden Parameter (wie in den obigen Beispielen im with-Abschnitt angegeben):

Der folgende Screenshot zeigt das Ergebnis der Erstellung eines Pull-Requests mit einer Datei, die einen Zugänglichkeitsfehler aufweist. Die Datei,

Der folgende Screenshot zeigt das Ergebnis der Erstellung einer Pull-Anfrage mit einer Datei, die einen Barrierefreiheitsfehler aufweist. Die Datei, bad-file.md, enthält Überschriftenebenen, die von Überschriftenebene 1 zu Überschriftenebene 3 springen und Ebene 2 überspringen, was einen Barrierefreiheitsfehler darstellt.

Probleme mit GitHub-Aktionen zu debuggen kann schwierig sein, da die Fehlermeldungen oft nicht das zugrunde liegende Problem genau widerspiegeln. Dieser Abschnitt enthält einige Beispiele für Fehler, die Sie möglicherweise sehen.

Falsch benanntes Geheimnis (nur SaaS)

Wenn der Name, den Sie Ihrem API-Schlüssel-Geheimnis geben, nicht mit dem im Workflow übereinstimmt, können Sie Fehler erhalten, die auf einen fehlenden Befehl hinweisen, anstatt auf einen nicht definierten Schlüssel:

Berechtigungsfehler

... line 41: Missing: command not found

Es gibt viele Stellen bei GitHub-Aktionen, an denen Berechtigungen falsch sein können. Zum Beispiel, wenn Sie ein nicht öffentliches Repository mit einer

Es gibt viele Stellen mit GitHub-Aktionen, an denen Berechtigungen falsch sein können. Beispielsweise erhalten Sie häufig den Fehler, dass das Repo nicht gefunden wurde, statt dass Sie keinen Zugriff darauf haben, wenn Sie ein nicht öffentliches Repo mit einer uses-Klausel referenzieren:

fatal: repository 'name' not found

Error: Resource not accessible by integration

Wenn Ihr Workflow mit dem Fehler Resource not accessible by integration nicht ausgeführt wird, können Sie die folgenden Berechtigungen zu Ihrem Workflow hinzufügen, um ihn zu beheben:

permissions:
  contents: read
  pull-requests: read 

Ihr vollständiger Workflow würde dann wie folgt aussehen:

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 }}

Von der Aktion überprüfte Dateien

Dateien mit diesen Erweiterungen werden auf Barrierefreiheitsfehler überprüft:

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

Dateien mit anderen Erweiterungen werden ignoriert, ebenso wie Dateien, die die Pull-Anfrage oder das Push löscht, und Dateien, die leer sind (Dateien, deren Inhalt nur aus Leerzeichen besteht).

Die Aktion überspringt auch jede Datei, deren Pfad ein Segment enthält, das mit einem Punkt beginnt (.). Nichts in Verzeichnissen wie .github oder .storybook und keine Punktdateien werden an den Linter gesendet.

Einschränkungen

Dateianzahl

Ab axe-linter-action v2.0.0 führt die Pull-Anfrage für jede geänderte Datei in der Pull-Anfrage Lint aus, unabhängig davon, wie viele Dateien die Pull-Anfrage enthält. Frühere Versionen forderten nur die erste Seite der geänderten Dateien von der GitHub-API an, was jede Ausführung auf etwa die ersten 30 Dateien beschränkte. Da dieses Limit still war, konnte eine Pull-Anfrage die Aktion bestehen, während Barrierefreiheitsfehler in den restlichen Dateien nicht gemeldet wurden. Wenn Sie noch v1.x verwenden, aktualisieren Sie auf v2.0.0, damit die gesamte Pull-Anfrage gelintet wird.

Push-Ereignisse funktionieren anders: Die Aktion vergleicht zwei Commits, und die GitHub-API gibt höchstens 300 Dateien für einen Vergleich zurück. Wenn ein Push mehr als 300 Dateien ändert, protokolliert die Aktion eine Warnung, um darauf hinzuweisen, dass einige Dateien nicht gescannt wurden. Das Ausführen der Aktion bei pull_request-Ereignissen, wie es die Beispiele auf dieser Seite tun, ist der Weg, um sicherzustellen, dass jede geänderte Datei überprüft wird.

Pfadausschlüsse

Die Aktion hat keinen Parameter zum Ausschließen von Pfaden. Jede geänderte Datei mit einer unterstützten Erweiterung wird gelintet, einschließlich Dateien in ausgelagerten Verzeichnissen wie einem eingecheckten node_modules. Wenn Ihr Repository Drittanbietercode eincheckt, erwarten Sie, dass diese Dateien gelintet werden, wann immer eine Pull-Anfrage sie ändert, was auch die Laufzeit verlängert.

Wenn Sie Kontrolle darüber benötigen, welche Pfade genau gelintet werden, verwenden Sie den Axe DevTools Linter Connector, den Sie auf beliebige Dateien oder Verzeichnisse verweisen können.

Dateigröße

Dateien, die größer als ungefähr 900 Kilobyte (900.000 Bytes) sind, werden übersprungen und als Warnung protokolliert. Die Axe DevTools Linter API hat ein Anfragengrößenlimit von 1 MB, daher werden übergroße Dateien herausgefiltert, um Antragsfehler zu vermeiden.

Nächste Schritte

Weitere Informationen zu den von Axe DevTools Linter verwendeten Regeln zur Überprüfung Ihres Codes finden Sie unter Barrierefreiheitsregeln. Wenn Sie mehr darüber erfahren möchten, wie Sie verhindern können, dass Dateien mit Barrierefreiheitsfehlern in Git committet werden, sehen Sie sich Verwendung eines Git Pre-Commit-Hooks an.