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
• .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

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.