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 locale del workflow include il parametro axe_linter_url ma non include il parametro 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

Il valore per axe_linter_url in questo esempio è letto 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 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
• .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 prevenire che file con errori di accessibilità siano inviati a Git, vedi Utilizzare un Git Pre-Commit-Hook.