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. Puoi ottenerne una seguendo i passaggi su Ottenere una Chiave API SaaS di Axe DevTools Linter, oppure puoi utilizzare una chiave API esistente dalla pagina delle impostazioni per il tuo account Axe. Se hai problemi a ottenere una chiave API, contatta il 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 fare andando alla pagina delle Impostazioni del tuo repo 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 flusso di lavoro per controllare i tuoi file alla ricerca di errori di accessibilità. Puoi creare un file denominato axe-linter.yml nella directory del tuo .github/workflows repository.

Puoi creare questo file online come nuovo flusso di lavoro sotto la scheda Azioni sulla pagina web del tuo repo (clicca su imposta un flusso di lavoro da solo sotto la sezione Inizia con GitHub Actions nella parte superiore della pagina Azioni ) oppure crearlo localmente e impegnarlo nel tuo repository.

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

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

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

Per SaaS

La versione SaaS del flusso di lavoro include il api_key parametro ma non include il axe_linter_url parametro:

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 flusso di lavoro include il axe_linter_url parametro ma non include il api_key parametro:

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

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

Per la versione on-premises di Axe DevTools Linter, non è necessaria una chiave API, ma la tua istanza di Axe DevTools Linter deve essere raggiungibile dai flussi di lavoro 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 silenziosamente reindirizzato a codice diverso dopo essere 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 il commit SHA per qualsiasi versione nella pagina dei rilasci di axe-linter-action. Puoi usare Dependabot per mantenere automaticamente aggiornato il tuo SHA fissato. Per ulteriori informazioni, vedi 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 with clausola):

Risultati del Workflow

Lo screenshot seguente mostra il risultato di creare una pull request con un file che ha 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 è 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

Ci sono molti punti nelle azioni GitHub dove i permessi possono essere errati. Ad esempio, se fai riferimento a un repo che non è pubblico con una uses clausola, spesso riceverai l'errore che il repo non è stato trovato invece di non avere accesso a 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 le seguenti autorizzazioni 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
• .html
• .vue
• .md
• .markdown
• .liquid

Limitazioni

Conteggio dei file

Nel caso di eventi di pull request, l'azione analizza tutti i file modificati. Per gli eventi di push, l'API di GitHub limita la lista dei file modificati a 300. Se un push include più di 300 file modificati, l'azione registra un avviso per indicare che alcuni file non sono stati analizzati.

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 impedire che file con errori di accessibilità vengano inseriti in Git, vedi Utilizzare un Git Pre-Commit-Hook.