Utilisation de l'action GitHub Axe DevTools Linter

Cet article vous montre comment utiliser l'action GitHub Axe DevTools Linter de Deque pour vérifier votre code à la recherche d'erreurs d'accessibilité lors de la création d'une requête pull GitHub. Une fois l'action exécutée, la requête pull contiendra des commentaires indiquant les erreurs d'accessibilité dans les fichiers engagés.

Les sections suivantes montrent les étapes pour configurer cette action GitHub avec votre dépôt.

Étape 1 : Obtenez une clé API (SaaS uniquement)

Pour Axe DevTools Linter SaaS, vous devez obtenir une clé API. Vous pouvez en obtenir une en suivant les étapes à Obtenir une clé API SaaS Axe DevTools Linter, ou vous pouvez utiliser une clé API existante de la page des paramètres pour votre compte Axe. Si vous rencontrez des problèmes pour obtenir une clé API, contactez le service d'assistance de Deque.

Étape 2 : Créez un secret de dépôt pour votre clé API (SaaS uniquement)

Si vous utilisez Axe DevTools Linter SaaS, vous devez ajouter votre clé API aux secrets de votre dépôt, ce que vous pouvez faire en vous rendant sur la page page Paramètres de votre dépôt sur GitHub. Pour plus d'informations, consultez Création de secrets chiffrés pour un dépôt sur les documents GitHub.

Pour l'exemple de flux de travail à l'étape suivante, les secrets doivent être appelés :

• AXE_LINTER_API_KEY pour la clé API

Étape 3 : Créez le flux de travail

Ensuite, vous devez créer un flux de travail pour vérifier vos fichiers pour les erreurs d'accessibilité. Vous pouvez créer un fichier nommé axe-linter.yml dans le répertoire .github/workflows de votre dépôt.

Vous pouvez créer ce fichier en ligne comme un nouveau flux de travail sous l'onglet Actions sur la page Web de votre dépôt (cliquez sur configurer un flux de travail vous-même dans la section Commencer avec GitHub Actions en haut de la page Actions) ou le créer localement et le valider dans votre dépôt.

Le axe-linter-action est invoqué dans le flux de travail lorsqu'une demande d'extraction est créée (on: [pull_request]). Le flux de travail utilise deux dépendances :

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

Les sections suivantes montrent des exemples de .github/workflows/axe-linter.yml que vous pouvez utiliser pour les versions SaaS ou sur site d'Axe DevTools Linter :

Pour SaaS

La version SaaS du flux de travail inclut le paramètre api_key mais n'inclut pas le paramètre axe_linter_url :

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

Pour sur site

La version sur site du flux de travail inclut le paramètre axe_linter_url mais n'inclut pas le paramètre api_key :

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

La valeur pour axe_linter_url est lue dans cet exemple à partir de l'environnement shell comme AXE_LINTER_URL.

Pour la version sur site de Axe DevTools Linter, vous n'avez pas besoin d'une clé API, mais votre instance de Axe DevTools Linter doit être accessible par les workflows GitHub via une connexion réseau.

Ancrage à un SHA de commit

À partir de v2.0.0, axe-linter-action utilise les versions immuables de GitHub. Cela signifie que @v2.0.0 ne peut pas être redirigé silencieusement vers un code différent après sa publication.

Pour une défense en profondeur supplémentaire, vous pouvez vous ancrer au SHA de commit complet au lieu de l'étiquette de version. Cela signifie que même si l'infrastructure des balises était contournée, votre workflow continuerait de référencer exactement le commit que vous avez initialement examiné :

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

Vous pouvez trouver le SHA du commit pour n'importe quelle version sur le page des versions de axe-linter-action. Vous pouvez utiliser Dependabot pour garder automatiquement votre SHA épinglé à jour. Pour plus d'informations, consultez Renforcement de la sécurité pour GitHub Actions sur les documents GitHub.

Paramètres de l'action GitHub

Le dequelabs/axe-linter-action utilise les paramètres suivants (spécifiés dans les exemples ci-dessus dans la clause with) :

Résultats du workflow

La capture d'écran suivante montre le résultat de la création d'une demande d'extraction avec un fichier qui a une erreur d'accessibilité. Le fichier, bad-file.md, contient des niveaux de titre qui passent du niveau 1 au niveau 3, en sautant le niveau 2, ce qui est une erreur d'accessibilité.

Dépannage

Déboguer les problèmes avec les actions GitHub peut être difficile parce que les messages d'erreur ne représentent souvent pas précisément le problème sous-jacent. Cette section contient quelques exemples d'erreurs que vous pourriez rencontrer.

Secret mal nommé (SaaS uniquement)

Si le nom que vous donnez à votre clé API ne correspond pas au nom dans le workflow, vous pouvez recevoir des erreurs concernant une commande manquante plutôt qu'une erreur indiquant que la clé n'est pas définie :

... line 41: Missing: command not found

Erreurs de permissions

Il existe de nombreux endroits avec les actions GitHub où les permissions peuvent être incorrectes. Par exemple, si vous référencez un dépôt qui n'est pas public avec une clause uses, vous recevrez souvent l'erreur que le dépôt n'a pas été trouvé au lieu de vous n'avez pas accès à celui-ci :

fatal: repository 'name' not found

Error: Resource not accessible by integration

Si votre flux de travail échoue avec l'erreur, Resource not accessible by integration, vous pouvez ajouter les permissions suivantes à votre flux de travail pour le corriger :

permissions:
  contents: read
  pull-requests: read 

Votre flux de travail complet ressemblerait alors à ceci :

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

Fichiers Vérifiés par l'Action

Les fichiers avec ces extensions seront vérifiés pour les erreurs d'accessibilité :

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

Limitations

Nombre de fichiers

Lors des événements de pull request, l'action analyse tous les fichiers modifiés. Lors des événements de push, l'API GitHub limite la liste des fichiers modifiés à 300. Si un push inclut plus de 300 fichiers modifiés, l'action enregistre un avertissement pour indiquer que certains fichiers n'ont pas été analysés.

Taille de fichier

Les fichiers de plus de 900 kilo-octets (900 000 octets) environ sont ignorés et enregistrés en tant qu'avertissement. L'API Axe DevTools Linter a une limite de taille de requête de 1 Mo, de sorte que les fichiers trop volumineux sont filtrés pour éviter les erreurs de requête.

Prochaines étapes

Pour des informations sur les règles utilisées par Axe DevTools Linter pour vérifier votre code, voir Règles d'Accessibilité. Si vous souhaitez en savoir plus sur la manière d'empêcher les fichiers avec des erreurs d'accessibilité d'être validés dans Git, voir Utilisation d'un Hook de Pré-validation Git.