Deutsch
Website-Menü

CI-Integration

Vorlagen zum direkten Einfügen, die die CLI (npx @surea11y/cli scan ...) in GitHub Actions, Bitbucket Pipelines, GitLab CI und Azure DevOps einbinden. Wenn Sie die Bibliothek statt über die CLI direkt aus Ihrem eigenen Node-Skript aufrufen, lesen Sie stattdessen INTEGRATION.md — diese Seite behandelt speziell die CLI als Pipeline-Schritt.

Die CLI scannt statisches HTML: Sie führt das JavaScript der Seite nicht aus. Das passt zu gebauten oder serverseitig gerenderten Seiten; für eine clientseitig gerenderte App oder Regeln, die ein Layout brauchen, scannen Sie stattdessen im Browser mit einem der Browser-Bindings.

Alle Vorlagen nutzen die Exit-Codes der CLI (0 bestanden, 1 mindestens ein — bzw. mit --baseline mindestens ein neues — fail-Ergebnis, 2 ein Aufruf- oder Scan-Fehler), um die Pipeline zu steuern; für ein einfaches Bestanden/Nicht-bestanden-Gating ist kein zusätzliches Skript nötig. Eine grüne Pipeline bedeutet, dass keine Prüfung fehlgeschlagen ist, bzw. keine neue. Sie ist keine Konformitätsaussage, und cantTell-Befunde lassen sie nicht scheitern.

GitHub Actions

Einfach: Gating über den Exit-Code

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: 22
      - run: npm ci && npm run build   # produce whatever static HTML you're scanning
      - run: npx @surea11y/cli scan ./dist/index.html

Damit schlägt der Job fehl, sobald irgendein fail-Ergebnis gefunden wird. Für eine bestehende Website mit bereits vorhandenen Verstößen verwenden Sie die Baseline-Variante unten, statt den Schritt zu deaktivieren.

Mit Baseline (bestehende Website, Gating nur bei neuen Verstößen)

# 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

Eine Baseline verhindert, dass bekannte Verstöße den Build scheitern lassen; sie macht sie nicht akzeptabel. Beheben Sie sie und verkleinern Sie die Datei mit der Zeit. Unter Baseline / Allowlist erfahren Sie, was als „bekannt“ und was als „neu“ gilt und wie Sie die Datei neu erzeugen, während Verstöße behoben werden.

SARIF zu GitHub Code Scanning hochladen

upload-sarif benötigt die Berechtigung security-events: write und lässt den Job selbst nicht fehlschlagen — kombinieren Sie es mit einem separaten Gating-Schritt (oder continue-on-error plus eigener Prüfung), wenn der Build bei neuen Verstößen auch fehlschlagen soll.

Befunde, die zu fail tendieren, sind standardmäßig warning-Alerts. Mit renderSarifReport(result, { leanFailAs: 'error' }) aus @surea11y/core/sarif erzeugt, sind sie errors, sodass ein Gating auf Fehler auch bei wahrscheinlichen Fehlschlägen stoppt (SARIF-Optionen); eine mit buildBaselineEntries(result, { leanFail: true }) geschriebene Baseline akzeptiert die, die eine Seite schon hat (Befunde mit Tendenz zu fail).

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: 22
      - 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

Siehe das SARIF-Berichtsformat und eine bekannte Einschränkung: Der Scan einer lokalen Datei in Ihrem Checkout erhält Inline-Annotationen in der Code-Scanning-Oberfläche; der Scan einer Live-URL nicht (SARIF/Code Scanning kann einen Befund nur einer tatsächlichen Datei im Repository zuordnen).

Bitbucket Pipelines

Bitbucket Pipelines hat kein eingebautes Dashboard für SARIF, das mit GitHub Code Scanning vergleichbar wäre. Der praktische Integrationspunkt ist daher der Exit-Code der CLI (optional ergänzt um --html als herunterladbares Pipeline-Artefakt), nicht --sarif.

pipelines:
  pull-requests:
    '**':
      - step:
          name: Accessibility scan
          image: node:22
          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

Der Schritt lässt die Pipeline über den Exit-Code der CLI fehlschlagen, genau wie jeder andere script-Eintrag; a11y-report.html (siehe den HTML-Bericht) wird als herunterladbares Build-Artefakt angehängt, sodass jemand im Review ihn öffnen kann, ohne den Scan lokal erneut auszuführen.

JUnit-Testberichte

GitLab, Azure DevOps, Jenkins und CircleCI zeigen JUnit-XML in ihren eigenen Testansichten: Jedes WCAG-Kriterium wird zu einer Suite und jede Regel zu einem Test (siehe JUnit-Bericht). Die CLI schreibt ihn mit --junit <path> (@surea11y/cli 1.1.0 oder neuer) aus demselben Scan wie ihre anderen Ausgaben, und der Bericht ändert nie ihren Exit-Code, sodass der Schritt den Build weiterhin steuert.

GitLab CI

a11y:
  image: node:22
  script:
    - npm ci
    - npm run build
    - npx @surea11y/cli scan ./dist/index.html --junit a11y.junit.xml
  artifacts:
    when: always
    reports:
      junit: a11y.junit.xml

when: always lädt den Bericht auch dann hoch, wenn der Exit-Code des Scans den Job fehlschlagen lässt — also genau dann, wenn sich ein Blick in das Merge-Request-Widget lohnt.

Azure DevOps

steps:
  - script: |
      npm ci
      npm run build
      npx @surea11y/cli scan ./dist/index.html --junit a11y.junit.xml
    displayName: Accessibility scan
  - task: PublishTestResults@2
    condition: succeededOrFailed()
    inputs:
      testResultsFormat: JUnit
      testResultsFiles: a11y.junit.xml

cantTell-Regeln erscheinen als übersprungene Tests, nie als Fehlschläge. Mit --baseline sind auch Fehlschläge, die schon in der Baseline stehen, übersprungene Tests. Für cantTell-Regeln als Fehlschläge hat die CLI kein Flag: Speichern Sie den Scan mit --json und erzeugen Sie den Bericht mit renderJunitReport(result, { cantTellAs: 'failure' }) aus @surea11y/core/junit (siehe JUnit-Bericht); dafür braucht das Projekt @surea11y/core in seinen eigenen devDependencies. { leanFailAs: 'failure' } ist die engere Wahl: Nur die cantTell-Befunde, die zu fail tendieren, werden zu Fehlschlägen, jeweils mit Begründung und den Schritten, um sie zu bestätigen. Beides ändert den Bericht, nicht den Exit-Code der CLI.

Minutenlimits bei Free-Tier und privaten Repositories

Wenn das Free-Tier Ihres Pipeline-Anbieters minutenbegrenzt ist (das Free-Tier von Bitbucket Pipelines umfasst zum Beispiel 50 Build-Minuten pro Monat für private Workspaces), ist ein jsdom-basierter Scan von statischem oder serverseitig gerendertem HTML (das, was die CLI macht) deutlich günstiger, als einen echten Browser zu steuern — in der CLI-Dokumentation steht, worauf Sie dabei verzichten (kein clientseitig gerenderter Inhalt, kein echtes CSS-Layout).