Utilizzo dell'Azione GitHub Axe DevTools Linter

Questo articolo mostra come utilizzare l'azione GitHub Axe DevTools Linter di Deque per controllare il tuo codice alla ricerca di errori di accessibilità al momento della creazione di una pull request su GitHub. Dopo l'esecuzione dell'azione, la pull request conterrà commenti che indicano gli errori di accessibilità nei file commessi.

Le sezioni seguenti mostrano i passaggi per configurare questa azione GitHub con il tuo repository.

Passo 1: Ottenere una Chiave API (Solo SaaS)

Per Axe DevTools Linter SaaS, è necessario ottenere una chiave API. È possibile ottenerne una seguendo i passaggi su Ottenere una Chiave API SaaS di Axe DevTools Linter oppure utilizzare una chiave API esistente da pagina delle impostazioni per il proprio account Axe. Se si riscontrano problemi nell'ottenere una chiave API, contattare servizio di assistenza Deque.

Passo 2: Creare un Segreto del Repository per la Tua Chiave API (Solo SaaS)

Se stai utilizzando Axe DevTools Linter SaaS, devi aggiungere la tua chiave API ai segreti del tuo repository, operazione che puoi eseguire andando alla pagina pagina delle Impostazioni del tuo repository su GitHub. Per maggiori informazioni, consulta Creare segreti criptati per un repository su GitHub Docs.

Per il flusso di lavoro di esempio nel passo successivo, i segreti dovrebbero essere chiamati:

• AXE_LINTER_API_KEY per la chiave API

Passo 3: Creare il Flusso di Lavoro

Successivamente, devi creare un workflow per controllare i tuoi file alla ricerca di errori di accessibilità. Puoi creare un file denominato axe-linter.yml nella directory .github/workflows del tuo repository.

Puoi creare questo file online come nuovo workflow sotto la scheda pagina Azioni sulla pagina web del tuo repository (clicca su imposta un flusso di lavoro da solo sotto la sezione Inizia con GitHub Actions in cima alla pagina pagina Azioni) oppure crearlo localmente e inviarlo al tuo repository.

Il axe-linter-action viene invocato nel workflow quando viene creata una pull request (on: [pull_request]). Il workflow utilizza due dipendenze:

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

Le seguenti sezioni mostrano esempi di .github/workflows/axe-linter.yml che puoi usare per le versioni SaaS o locali di Axe DevTools Linter:

Per SaaS

La versione SaaS del workflow include il parametro api_key ma non include il parametro 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 }}

Per On-Prem

La versione on-prem del workflow include il parametro axe_linter_url e imposta api_key a un valore segnaposto:

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

Il valore per axe_linter_url in questo esempio è letto dall'ambiente shell come AXE_LINTER_URL.

Per la versione on-prem di Axe DevTools Linter, non è necessaria una chiave API: il server on-prem è autorizzato con la propria chiave di licenza e non valida il valore api_key. A partire da axe-linter-action v2.0.0, tuttavia, api_key è un input richiesto, quindi è necessario fornire un valore segnaposto non vuoto (come on-prem-no-key-required sopra) altrimenti l'azione fallisce con Input required and not supplied: api_key. La tua istanza di Axe DevTools Linter deve essere anche accessibile ai flussi di lavoro di GitHub tramite una connessione di rete.

Fissare a un Commit SHA

A partire da v2.0.0, axe-linter-action utilizza GitHub Immutable Releases. Questo significa che @v2.0.0 non può essere reindirizzato silenziosamente a diverso codice dopo che è stato pubblicato.

Per una difesa in profondità aggiuntiva, puoi fissare la lunghezza completa del commit SHA anziché il tag della versione. Ciò significa che anche se l'infrastruttura del tag venisse mai aggirata, il tuo flusso di lavoro continuerebbe a fare riferimento esattamente al commit che hai originariamente revisionato:

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

Puoi trovare l'SHA del commit per qualsiasi versione su pagina dei rilasci di axe-linter-action. Puoi utilizzare Dependabot per mantenere automaticamente aggiornato il tuo SHA fissato. Per maggiori informazioni, consulta Rafforzamento della sicurezza per GitHub Actions su GitHub Docs.

Parametri dell'azione GitHub

Il dequelabs/axe-linter-action utilizza i seguenti parametri (specificati negli esempi sopra nella clausola with):

Risultati del Workflow

Lo screenshot seguente mostra il risultato della creazione di una pull request con un file che presenta un errore di accessibilità. Il file, bad-file.md, contiene livelli di intestazione che vanno dal livello 1 al livello 3, saltando il livello 2, il che costituisce un errore di accessibilità.

Risoluzione dei Problemi

Debuggare problemi con le azioni GitHub può essere impegnativo perché spesso i messaggi di errore non rappresentano accuratamente il problema sottostante. Questa sezione contiene alcuni esempi di errori che potresti vedere.

Segreto Nome Sbagliato (Solo SaaS)

Se il nome che dai al tuo segreto della chiave API non corrisponde al nome nel flusso di lavoro, potresti ricevere errori su un comando mancante piuttosto che un errore perché la chiave non è definita:

... line 41: Missing: command not found

Errori di Permessi

Esistono molti luoghi con GitHub actions dove i permessi possono essere errati. Ad esempio, se fai riferimento a un repository che non è pubblico con una clausola uses, spesso riceverai l'errore che non è stato trovato il repository invece che non hai accesso ad esso:

fatal: repository 'name' not found

Error: Resource not accessible by integration

Se il tuo workflow non riesce a essere eseguito con l'errore Resource not accessible by integration, puoi aggiungere i seguenti permessi al tuo workflow per risolverlo:

permissions:
  contents: read
  pull-requests: read 

Il tuo workflow completo sarebbe quindi simile a questo:

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

File Controllati dall'Azione

I file con queste estensioni verranno controllati per errori di accessibilità:

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

I file con qualsiasi altra estensione vengono ignorati, così come i file che la pull request o il push eliminano e i file vuoti (file il cui contenuto è solo spazio bianco).

L'azione ignora anche qualsiasi file il cui percorso contiene un segmento che inizia con un punto (.). Nulla nelle directory come .github o .storybook, e nessun file nascosto, viene inviato al linter.

Limitazioni

Conteggio dei file

A partire da axe-linter-action v2.0.0, le pull request eseguono il linting su ogni file modificato nella pull request, a prescindere dal numero di file contenuti nella pull request. Le versioni precedenti richiedevano solo la prima pagina di file modificati dall'API di GitHub, limitando ogni esecuzione ai primi 30 file circa. Poiché quel limite era silenzioso, una pull request poteva passare l'azione mentre rimanevano errori di accessibilità non riportati nei file restanti. Se stai ancora utilizzando v1.x, aggiorna a v2.0.0 affinché l'intera pull request sia sottoposta a linting.

Gli eventi push funzionano in modo diverso: l'azione confronta due commit e l'API di GitHub restituisce al massimo 300 file per un confronto. Se un push modifica più di 300 file, l'azione registra un avviso per indicare che alcuni file non sono stati scansionati. Eseguire l'azione sugli eventi pull_request, come fanno gli esempi in questa pagina, è il modo per assicurarsi che ogni file modificato sia controllato.

Esclusioni di percorso

L'azione non ha parametri per escludere percorsi. Ogni file modificato con un'estensione supportata è sottoposto a linting, inclusi i file nelle directory di terze parti come un node_modules verificato. Se il tuo repository include codice di terze parti, aspettati che quei file vengano sottoposti a linting ogni volta che una pull request li modifica, il che aumenta anche la durata dell'esecuzione.

Se hai bisogno di controllare esattamente quali percorsi vengono sottoposti a linting, usa il connettore Axe DevTools Linter, che puoi puntare verso i file o le directory che scegli.

Dimensione dei file

I file più grandi di circa 900 kilobyte (900.000 byte) vengono saltati e registrati come avviso. L'API di Axe DevTools Linter ha un limite di dimensione della richiesta di 1 MB, quindi i file sovradimensionati vengono filtrati per prevenire errori di richiesta.

Passaggi Successivi

Per informazioni sulle regole utilizzate da Axe DevTools Linter per controllare il tuo codice, vedi Regole di Accessibilità. Se desideri sapere di più su come prevenire che file con errori di accessibilità siano inviati a Git, vedi Utilizzare un Git Pre-Commit-Hook.