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 et assigne à api_key une valeur de remplacement :

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

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 d'Axe DevTools Linter, vous n'avez pas besoin de clé API : votre serveur sur site est autorisé avec sa propre clé de licence et ne valide pas la valeur api_key. Cependant, à partir de axe-linter-action v2.0.0, api_key est une entrée requise, vous devez donc fournir une valeur de remplacement non vide (comme on-prem-no-key-required ci-dessus) ou l'action échoue avec Input required and not supplied: api_key. Votre instance d'Axe DevTools Linter doit également être accessible aux flux de travail 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
• .esm
• .html
• .htm
• .vue
• .md
• .markdown
• .liquid

Les fichiers ayant toute autre extension sont ignorés, tout comme les fichiers que la demande de tirage ou le push supprime et les fichiers qui sont vides (fichiers dont le contenu n'est constitué que d'espaces).

L'action ignore également tout fichier dont le chemin contient un segment commençant par un point (.). Rien dans les répertoires tels que .github ou .storybook, et aucun fichier caché, n'est envoyé au linter.

Limitations

Nombre de fichiers

À partir de axe-linter-action v2.0.0, la demande de tirage exécute le lint sur chaque fichier modifié dans la demande, quelle que soit la quantité de fichiers qu'elle contient. Les versions antérieures demandaient uniquement la première page des fichiers modifiés via l'API GitHub, limitant chaque exécution à environ les 30 premiers fichiers. Parce que cette limite était silencieuse, une demande de tirage pouvait réussir l'action tandis que des erreurs d'accessibilité dans les fichiers restants n'étaient pas signalées. Si vous utilisez toujours v1.x, passez à v2.0.0 afin que toute la demande de tirage soit analysée.

Les événements de push fonctionnent différemment : l'action compare deux commits, et l'API GitHub renvoie au maximum 300 fichiers pour une comparaison. Si un push modifie plus de 300 fichiers, l'action consigne un avertissement pour indiquer que certains fichiers n'ont pas été analysés. Lancer l'action sur les événements pull_request, comme le font les exemples sur cette page, est le moyen de s'assurer que chaque fichier modifié est vérifié.

Exclusions de chemin

L'action n'a aucun paramètre pour exclure des chemins. Chaque fichier modifié avec une extension prise en charge est analysé, y compris les fichiers dans des répertoires vendus tels qu'un node_modules pris en compte. Si votre dépôt inclut du code tiers, attendez-vous à ce que ces fichiers soient analysés chaque fois qu'une demande de tirage les modifie, ce qui augmente également la durée de l'exécution.

Si vous avez besoin de contrôler précisément les chemins analysés, utilisez le connecteur Axe DevTools Linter, que vous pouvez pointer vers les fichiers ou répertoires de votre choix.

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.