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 obtener una siguiendo los pasos en Obtención de una Clave API de Axe DevTools Linter SaaS, o puedes usar una clave API existente desde la página de configuración para tu cuenta de Axe. Si tienes problemas para obtener una clave API, contacta al 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 añadir tu clave API a los secretos de tu repositorio, lo cual puedes hacer yendo a la Configuración de tu repositorio en GitHub. Para más información, consulta Creación de secretos cifrados para un repositorio en la documentación de GitHub.

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 verificar si tus archivos tienen errores de accesibilidad. Puedes crear un archivo llamado axe-linter.yml en el .github/workflows directorio 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 en la sección Comenzar con Acciones de GitHub en la parte superior de la página de Acciones ) o crearlo localmente y comprometerlo con 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 local de Axe DevTools Linter:

Para SaaS

La versión SaaS del flujo de trabajo incluye el api_key parámetro pero no incluye el axe_linter_url parámetro:

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 axe_linter_url parámetro pero no incluye el api_key parámetro:

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

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 API, pero tu instancia de Axe DevTools Linter debe ser accesible para 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 usa Releases Inmutables de GitHub. Esto significa que @v2.0.0 no puede ser redirigido 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 del commit para cualquier versión en la 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 la documentación de GitHub.

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 with cláusula):

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 del nivel 1 al nivel 3, saltando 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

Existen muchos lugares en las acciones de GitHub donde los permisos pueden ser incorrectos. Por ejemplo, si haces referencia a un repositorio que no es público con una uses cláusula, a menudo recibirás el error de que el repositorio no fue encontrado 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 revisar tu código, consulta Reglas de Accesibilidad. Si deseas saber más sobre cómo evitar que se cometan archivos con errores de accesibilidad en Git, consulta Usar un Hook de Pre-Commit de Git.