Usando a Ação GitHub do Axe DevTools Linter

Este artigo mostra como usar a ação GitHub do Axe DevTools Linter da Deque para verificar seu código em busca de erros de acessibilidade ao criar uma solicitação de pull no GitHub. Após a execução da ação, a solicitação de pull conterá comentários mostrando os erros de acessibilidade nos arquivos comprometidos.

As seções a seguir mostram os passos para configurar esta ação do GitHub com seu repositório.

Passo 1: Obter uma Chave da API (Somente SaaS)

Para o Axe DevTools Linter SaaS, você precisa obter uma chave de API. Você pode obter uma seguindo os passos em Obtendo uma Chave de API do Axe DevTools Linter SaaS, ou pode usar uma chave de API existente de página de configurações para sua conta Axe. Se tiver problemas para obter uma chave de API, entre em contato com atendimento ao cliente da Deque.

Passo 2: Criar um Segredo do Repositório para Sua Chave da API (Somente SaaS)

Se você estiver usando o Axe DevTools Linter SaaS, precisa adicionar sua chave de API aos segredos do seu repositório, o que pode ser feito indo à página Configuração do seu repositório no GitHub. Para mais informações, consulte Criando segredos criptografados para um repositório no GitHub Docs.

Para o fluxo de trabalho de exemplo no próximo passo, os segredos devem ser chamados de:

• AXE_LINTER_API_KEY para a chave de API

Passo 3: Criar o Fluxo de Trabalho

Em seguida, você deve criar um fluxo de trabalho para verificar seus arquivos em busca de erros de acessibilidade. Você pode criar um arquivo chamado axe-linter.yml no diretório .github/workflows do seu repositório.

Você pode criar este arquivo online como um novo fluxo de trabalho na aba Ações na página do seu repositório (clique em configure um fluxo de trabalho por você mesmo na seção Comece a usar o GitHub Actions no topo da página Ações) ou criá-lo localmente e enviá-lo ao seu repositório.

O axe-linter-action é invocado no fluxo de trabalho quando uma solicitação de pull é criada (on: [pull_request]). O fluxo de trabalho usa duas dependências:

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

As seções a seguir mostram exemplos de .github/workflows/axe-linter.yml que você pode usar para as versões SaaS ou on-prem do Axe DevTools Linter:

Para SaaS

A versão SaaS do fluxo de trabalho inclui o parâmetro api_key, mas não inclui o parâmetro 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 }}

Para On-Premises

A versão on-prem do fluxo de trabalho inclui o parâmetro axe_linter_url, mas não inclui o parâmetro 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

O valor para axe_linter_url é lido neste exemplo do ambiente de shell como AXE_LINTER_URL.

Para a versão local do Axe DevTools Linter, você não precisa de uma chave de API, mas a sua instância do Axe DevTools Linter deve ser acessível para os fluxos de trabalho do GitHub através de uma conexão de rede.

Fixar em um Commit SHA

Começando com v2.0.0, axe-linter-action usa Releases Imutáveis do GitHub. Isso significa que @v2.0.0 não pode ser redirecionado silenciosamente para um código diferente após ter sido publicado.

Para uma defesa adicional em profundidade, você pode fixar no SHA completo do commit em vez da tag de versão. Isso significa que, mesmo se a infraestrutura de tags for comprometida, seu fluxo de trabalho continuará a referenciar exatamente o commit que você revisou originalmente:

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

Você pode encontrar o SHA do commit para qualquer versão no axe-linter-action. Você pode usar Dependabot para manter automaticamente seu SHA fixo atualizado. Para mais informações, consulte Reforço de segurança para GitHub Actions no GitHub Docs.

Parâmetros da Ação do GitHub

O dequelabs/axe-linter-action utiliza os seguintes parâmetros (especificados nos exemplos acima na cláusula with):

Resultados do Fluxo de Trabalho

A seguinte captura de tela mostra o resultado de criar uma solicitação de pull com um arquivo que tem um erro de acessibilidade. O arquivo, bad-file.md, contém níveis de cabeçalhos que vão do nível de cabeçalho 1 ao nível de cabeçalho 3, pulando o nível 2, o que é um erro de acessibilidade.

Solução de Problemas

Depurar problemas com as ações do GitHub pode ser desafiador porque as mensagens de erro frequentemente não representam o problema subjacente com precisão. Esta seção contém alguns exemplos de erros que você pode encontrar.

Segredo Nomeado Incorretamente (Somente SaaS)

Se o nome que você der ao segredo da sua chave de API não corresponder ao nome no fluxo de trabalho, você pode receber erros sobre um comando ausente em vez de um erro que a chave não está definida:

... line 41: Missing: command not found

Erros de Permissão

Existem muitos lugares com ações do GitHub onde as permissões podem estar incorretas. Por exemplo, se você fizer referência a um repositório que não é público com uma cláusula uses, você frequentemente receberá o erro de que o repositório não foi encontrado em vez de que você não tem acesso a ele:

fatal: repository 'name' not found

Error: Resource not accessible by integration

Se o seu fluxo de trabalho falhar ao executar com o erro, Resource not accessible by integration, você pode adicionar as seguintes permissões ao seu fluxo de trabalho para corrigi-lo:

permissions:
  contents: read
  pull-requests: read 

Seu fluxo de trabalho completo ficaria assim:

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

Arquivos Verificados pela Ação

Arquivos com essas extensões serão verificados quanto a erros de acessibilidade:

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

Limitações

Contagem de arquivos

Em eventos de pull request, a ação escaneia todos os arquivos alterados. Em eventos de push, a API do GitHub limita a lista de arquivos alterados a 300. Se um push incluir mais de 300 arquivos alterados, a ação registra um aviso indicando que alguns arquivos não foram escaneados.

Tamanho do arquivo

Arquivos maiores que aproximadamente 900 kilobytes (900.000 bytes) são ignorados e registrados como um aviso. A API do Axe DevTools Linter tem um limite de 1 MB para o tamanho das requisições, então arquivos muito grandes são filtrados para evitar erros nas requisições.

Próximos Passos

Para informações sobre as regras usadas pelo Axe DevTools Linter para verificar seu código, consulte Regras de Acessibilidade. Se você gostaria de saber mais sobre como evitar que arquivos com erros de acessibilidade sejam cometidos no Git, veja Usando um Pré-Commit Hook do Git.