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 Axe DevTools Linter SaaS müssen Sie einen API-Schlüssel erhalten. Sie können einen erhalten, indem Sie die Schritte unter Einen API-Schlüssel für Axe DevTools Linter SaaS erhaltenausführen, oder Sie können einen vorhandenen API-Schlüssel aus der Einstellungsseite für Ihr Axe-Konto verwenden. Wenn Sie Probleme beim Erhalten eines API-Schlüssels haben, wenden Sie sich an 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 Repositorys hinzufügen. Dazu gehen Sie auf die Einstellungen -Seite Ihres Repos auf GitHub. 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 in das .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 erstellen Sie sie lokal und committen Sie sie in Ihrem Repo.

Der axe-linter-action wird im Workflow aufgerufen, wenn ein Pull-Request erstellt wird (on: [pull_request]). Der Workflow verwendet zwei Abhängigkeiten:

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

Die folgenden Abschnitte zeigen Beispiele für .github/workflows/axe-linter.yml , die Sie für die SaaS- oder On-Premise-Versionen von Axe DevTools Linter verwenden können:

Für SaaS

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

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

Für die lokale Version von Axe DevTools Linter benötigen Sie keinen API-Schlüssel, aber Ihre Instanz von Axe DevTools Linter muss über eine Netzwerkverbindung für GitHub Workflows erreichbar sein.

Festlegen auf ein Commit-SHA

Beginnend mit v2.0.0, verwendet axe-linter-action GitHub Immutable Releases . Das bedeutet, dassnicht unbemerkt auf anderen Code umgelenkt werden kann, nachdem es veröffentlicht wurde. @v2.0.0 Für zusätzlichen Schutz können Sie sich auf das vollständige Commit-SHA anstelle des Versionstags festlegen. Das bedeutet, selbst wenn die Tag-Infrastruktur jemals umgangen werden sollte, würde Ihr Workflow weiterhin genau das Commit referenzieren, das Sie ursprünglich überprüft haben:

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

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

axe-linter-action Releases-Seite finden. Sie könnenDependabot verwenden, um Ihr festgelegtes SHA automatisch auf dem neuesten Stand zu halten. Weitere Informationen finden Sie unter Sicherheitshärtung für GitHub Actions in den GitHub-Dokumentationen. GitHub Action Parameter

Die

verwendet die folgenden Parameter (wie in den obigen Beispielen in der dequelabs/axe-linter-action Klausel angegeben): with Name

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

, enthält Überschriftsebenen von Ebene 1 bis Ebene 3, wobei Ebene 2 ausgelassen wird, was einen Zugänglichkeitsfehler darstellt. bad-file.mdEin Pull-Request auf GitHub und der vom Axe DevTools Linter GitHub Action gekennzeichnete Fehler. Die Datei auf der rechten Seite des Bildes enthält einen Zugänglichkeitsfehler, bei dem die Überschriftsebene 2 übersprungen wird. Es gibt eine Fehlermeldung von der GitHub-Aktion, die Details über den Fehler bereitstellt.

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

Klausel referenzieren, erhalten Sie oft den Fehler, dass das Repository nicht gefunden wurde, anstatt dass Sie keinen Zugriff darauf haben: uses clause, you often will receive the error that the repo wasn't found instead of you don't have access to it:

fatal: repository 'name' not found

Error: Resource not accessible by integration

Wenn Ihr Workflow mit dem Fehler Resource not accessible by integrationfehlschlägt, können Sie die folgenden Berechtigungen zu Ihrem Workflow hinzufügen, um das Problem 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
• .html
• .vue
• .md
• .markdown
• .liquid

Einschränkungen

Dateianzahl

Bei Pull-Request-Ereignissen scannt die Aktion alle geänderten Dateien. Bei Push-Ereignissen begrenzt die GitHub-API die Liste der geänderten Dateien auf 300. Wenn ein Push mehr als 300 geänderte Dateien enthält, protokolliert die Aktion eine Warnung, die darauf hinweist, dass einige Dateien nicht gescannt wurden.

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

Für Informationen über die Regeln, die Axe DevTools Linter zur Prüfung Ihres Codes verwendet, siehe Barrierefreiheitsregeln. Wenn Sie mehr darüber erfahren möchten, wie das Einchecken von Dateien mit Barrierefreiheitsfehlern in Git verhindert werden kann, siehe Verwendung eines Git Pre-Commit-Hooks.