Integración con CI

Plantillas listas para pegar que envuelven la CLI (npx @surea11y/cli scan ...) en GitHub Actions y Bitbucket Pipelines. Si llamas a la librería directamente desde tu propio script de Node en lugar de usar la CLI, consulta en su lugar INTEGRATION.md: esta página trata específicamente sobre la CLI como paso del pipeline de CI.

Todas estas plantillas utilizan los códigos de salida de la CLI (0 si no se encuentran fallos, 1 si existe al menos un resultado fail (o uno nuevo al utilizar --baseline) y 2 si se produce un error de uso o de análisis) para controlar el pipeline de CI; no se necesita scripting adicional para un control básico de aprobado/fallido.

GitHub Actions

Básico: controlar según el código de salida

name: Accessibility scan
on: [pull_request]
 
jobs:
  a11y-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci && npm run build   # produce whatever static HTML you're scanning
      - run: npx @surea11y/cli scan ./dist/index.html

Esto hace que el job falle en el momento en que se encuentra cualquier resultado fail. Para un sitio existente con violaciones preexistentes, consulta la variante con baseline más abajo en lugar de deshabilitar el paso.

Con un baseline (sitio existente, controlar solo las violaciones nuevas)

# Once, locally: record every current fail occurrence, commit the file.
$ surea11y scan ./dist/index.html --write-baseline a11y-baseline.json
$ git add a11y-baseline.json

      - run: npm ci && npm run build
      - run: npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json

Consulta Baseline / allowlist para ver qué cuenta como "conocido" frente a "nuevo", y cómo regenerar el archivo a medida que se corrigen violaciones.

Subir SARIF a GitHub Code Scanning

upload-sarif necesita el permiso security-events: write y no hace fallar el job por sí mismo: combínalo con un paso de control independiente (o continue-on-error + tu propia comprobación) si también quieres que la compilación falle ante violaciones nuevas.

name: Accessibility scan
on: [pull_request]
 
permissions:
  contents: read
  security-events: write
 
jobs:
  a11y-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci && npm run build
      - name: Scan (report, don't fail the job here)
        run: npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json --sarif results.sarif
        continue-on-error: true
        id: scan
      - name: Upload SARIF to Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
      - name: Fail the job on new violations
        if: steps.scan.outcome == 'failure'
        run: exit 1

Consulta el formato del informe SARIF y una limitación conocida: un análisis de un archivo local en tu checkout obtiene anotaciones en línea en la interfaz de Code Scanning; un análisis de una URL en vivo no las obtiene (SARIF/Code Scanning solo puede asociar un hallazgo con un archivo real del repositorio).

Bitbucket Pipelines

Bitbucket Pipelines no tiene un panel integrado que consuma SARIF equivalente a GitHub Code Scanning, así que el código de salida de la CLI (más, opcionalmente, --html como artefacto descargable del pipeline de CI) es el punto de integración práctico en lugar de --sarif.

pipelines:
  pull-requests:
    '**':
      - step:
          name: Accessibility scan
          image: node:20
          script:
            - npm ci
            - npm run build
            - npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json --html a11y-report.html
          artifacts:
            - a11y-report.html

El paso hace fallar el pipeline de CI según el código de salida de la CLI, exactamente igual que cualquier otra entrada de script; a11y-report.html (consulta el informe HTML) se adjunta como artefacto de compilación descargable para que quien revise pueda abrirlo sin volver a ejecutar el análisis localmente.

Límites de minutos en el nivel gratuito/repos privados

Si el nivel gratuito de tu proveedor de pipelines de CI tiene un límite de minutos (el nivel gratuito de Bitbucket Pipelines es de 50 minutos de compilación al mes en workspaces privados, por ejemplo), un análisis basado en jsdom de HTML estático/renderizado en el servidor (lo que hace la CLI) es mucho más económico que controlar un navegador real mediante automatización. Consulta la documentación de la CLI para ver qué se sacrifica con eso (sin contenido renderizado en el cliente ni un motor de diseño CSS real).