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 e define api_key como um valor de espaço reservado:

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

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

Para a versão on-prem do Axe DevTools Linter, você não precisa de uma chave de API: seu servidor on-prem é autorizado com sua própria chave de licença e não valida o valor de api_key. A partir de axe-linter-action v2.0.0, no entanto, api_key é uma entrada obrigatória, portanto, você deve fornecer um valor de espaço reservado não vazio (como on-prem-no-key-required acima) ou a ação falhará com Input required and not supplied: api_key. Sua instância do Axe DevTools Linter também deve ser acessível aos fluxos de trabalho do GitHub via 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
• .esm
• .html
• .htm
• .vue
• .md
• .markdown
• .liquid

Arquivos com qualquer outra extensão são ignorados, assim como arquivos que o pull request ou o push exclui e arquivos que estão vazios (arquivos cujo conteúdo é apenas espaços em branco).

A ação também ignora qualquer arquivo cujo caminho contenha um segmento que comece com um ponto (.). Nada em diretórios como .github ou .storybook, e nenhum arquivo oculto, é enviado para o linter.

Limitações

Contagem de arquivos

A partir de axe-linter-action v2.0.0, pull request executa o lint em todos os arquivos alterados no pull request, não importa quantos arquivos o pull request contenha. Versões anteriores solicitavam apenas a primeira página de arquivos alterados da API do GitHub, o que limitava cada execução a aproximadamente os primeiros 30 arquivos. Como esse limite era silencioso, um pull request podia passar na ação enquanto erros de acessibilidade nos arquivos restantes não eram relatados. Se você ainda está usando v1.x, atualize para v2.0.0 para que o pull request completo seja analisado.

Eventos de push funcionam de forma diferente: a ação compara dois commits, e a API do GitHub retorna no máximo 300 arquivos para uma comparação. Se um push modifica mais de 300 arquivos, a ação registra um aviso para indicar que alguns arquivos não foram escaneados. Executar a ação em eventos de pull_request, como os exemplos nesta página fazem, é a maneira de garantir que cada arquivo alterado seja verificado.

Exclusões de caminho

A ação não possui um parâmetro para excluir caminhos. Todo arquivo alterado com uma extensão suportada é analisado, incluindo arquivos em diretórios de fornecedores, como um node_modules verificado. Se o seu repositório faz commit de código de terceiros, espere que esses arquivos sejam analisados sempre que um pull request os alterar, o que também aumenta o tempo de execução.

Se você precisa de controle sobre quais caminhos são analisados, use o Conector do Linter Axe DevTools, que pode ser direcionado para os arquivos ou diretórios que você escolher.

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.