Uso de la Acción de GitHub Axe DevTools Linter

Este artículo te muestra cómo usar la acción de GitHub Axe DevTools Linter de Deque para comprobar si tu código tiene errores de accesibilidad al crear una solicitud de extracción en GitHub. Después de ejecutar la acción, la solicitud de extracción contendrá comentarios que muestran los errores de accesibilidad en los archivos comprometidos.

Las siguientes secciones muestran los pasos para configurar esta acción de GitHub con tu repositorio.

Paso 1: Obtener una Clave API (Sólo SaaS)

Para Axe DevTools Linter SaaS, necesitas obtener una clave API. Puedes conseguir una siguiendo los pasos en Obtención de una Clave API de Axe DevTools Linter SaaS, o puedes usar una clave API existente de la página de configuración para tu cuenta de Axe. Si tienes problemas para obtener una clave API, contacta a servicio de ayuda de Deque.

Paso 2: Crear un Secreto del Repositorio para tu Clave API (Sólo SaaS)

Si estás usando Axe DevTools Linter SaaS, necesitas agregar tu clave API a los secretos de tu repositorio, lo cual puedes hacer yendo a la página Configuración de tu repositorio en GitHub. Para más información, consulta Creación de secretos cifrados para un repositorio en GitHub Docs.

Para el flujo de trabajo de ejemplo en el siguiente paso, los secretos deben llamarse:

• AXE_LINTER_API_KEY para la clave API

Paso 3: Crear el Flujo de Trabajo

A continuación, debes crear un flujo de trabajo para revisar tus archivos en busca de errores de accesibilidad. Puedes crear un archivo llamado axe-linter.yml en el directorio .github/workflows de tu repositorio.

Puedes crear este archivo en línea como un nuevo flujo de trabajo bajo la pestaña Acciones en la página web de tu repositorio (haz clic en configurar un flujo de trabajo tú mismo bajo la sección Comenzar con Acciones de GitHub en la parte superior de la página Acciones) o crearlo localmente y confirmarlo en tu repositorio.

El axe-linter-action se invoca en el flujo de trabajo cuando se crea una solicitud de extracción (on: [pull_request]). El flujo de trabajo utiliza dos dependencias:

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

Las siguientes secciones muestran ejemplos de .github/workflows/axe-linter.yml que puedes usar para las versiones SaaS o en local de Axe DevTools Linter:

Para SaaS

La versión SaaS del flujo de trabajo incluye el parámetro api_key pero no incluye el 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 Local

La versión local del flujo de trabajo incluye el parámetro axe_linter_url y configura api_key con un valor de marcador de posición:

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

El valor para axe_linter_url se lee en este ejemplo desde el entorno de shell como AXE_LINTER_URL.

Para la versión local de Axe DevTools Linter, no necesitas una clave de API: tu servidor local está autorizado con su propia clave de licencia y no valida el valor de api_key. Sin embargo, a partir de axe-linter-action v2.0.0, api_key es una entrada requerida, por lo que debes proporcionar un valor de marcador de posición no vacío (como on-prem-no-key-required arriba) o la acción fallará con Input required and not supplied: api_key. Tu instancia de Axe DevTools Linter también debe ser accesible a los flujos de trabajo de GitHub a través de una conexión de red.

Fijación a un SHA de Commit

A partir de v2.0.0, axe-linter-action utiliza Releases Inmutables de GitHub. Esto significa que @v2.0.0 no se puede redirigir silenciosamente a un código diferente después de haber sido publicado.

Para una defensa adicional en profundidad, puedes fijar al SHA completo del commit en lugar de la etiqueta de versión. Esto significa que incluso si la infraestructura de etiquetas fuera alguna vez comprometida, tu flujo de trabajo continuaría referenciando exactamente el commit que originalmente revisaste:

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

Puedes encontrar el SHA de confirmación para cualquier versión en el página de releases de axe-linter-action. Puedes usar Dependabot para mantener automáticamente tu SHA fijado actualizado. Para más información, consulta Recursos para fortalecer la seguridad en GitHub Actions en GitHub Docs.

Parámetros de la Acción de GitHub

El dequelabs/axe-linter-action utiliza los siguientes parámetros (especificados en los ejemplos anteriores en la cláusula with):

Resultados del Flujo de Trabajo

La siguiente captura de pantalla muestra el resultado de crear una solicitud de extracción con un archivo que tiene un error de accesibilidad. El archivo, bad-file.md, contiene niveles de encabezado que van desde el nivel 1 al nivel 3, omitiendo el nivel 2, lo cual es un error de accesibilidad.

Solución de Problemas

Depurar problemas con las acciones de GitHub puede ser un desafío porque los mensajes de error a menudo no representan con precisión el problema subyacente. Esta sección contiene algunos ejemplos de errores que podrías ver.

Secreto Incorrectamente Nombrado (Solo SaaS)

Si el nombre que le das a tu secreto de clave API no coincide con el nombre en el flujo de trabajo, puedes recibir errores sobre un comando faltante en lugar de un error que indique que la clave no está definida:

... line 41: Missing: command not found

Errores de Permisos

Hay muchos lugares con acciones de GitHub donde los permisos pueden ser incorrectos. Por ejemplo, si haces referencia a un repositorio que no es público con una cláusula uses, a menudo recibirás el error de que el repositorio no se encontró en lugar de que no tienes acceso a él:

fatal: repository 'name' not found

Error: Resource not accessible by integration

Si tu flujo de trabajo no se ejecuta debido al error Resource not accessible by integration, puedes agregar los siguientes permisos a tu flujo de trabajo para solucionarlo:

permissions:
  contents: read
  pull-requests: read 

Tu flujo de trabajo completo se vería así:

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

Archivos Revisados por la Acción

Los archivos con estas extensiones serán revisados por errores de accesibilidad:

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

Limitaciones

Cantidad de archivos

En los eventos de solicitudes de extracción, la acción escanea todos los archivos modificados. En los eventos de push, la API de GitHub limita la lista de archivos modificados a 300. Si un push incluye más de 300 archivos modificados, la acción registra una advertencia para indicar que algunos archivos no fueron escaneados.

Tamaño de los archivos

Los archivos que superen aproximadamente 900 kilobytes (900,000 bytes) se omiten y se registran como advertencia. La API de Axe DevTools Linter tiene un límite de tamaño de solicitud de 1 MB, por lo que los archivos de gran tamaño se filtran para prevenir errores de solicitud.

Próximos Pasos

Para obtener información sobre las reglas utilizadas por Axe DevTools Linter para verificar tu código, consulta Reglas de Accesibilidad. Si deseas saber más sobre cómo prevenir que los archivos con errores de accesibilidad sean confirmados en Git, consulta Usar un Hook de Pre-Commit de Git.