CI/CD Integration

Run Speakable in your build pipeline to catch accessibility regressions on every pull request.

Installation

Install Speakable as a dev dependency in your project:

Terminal

npm install --save-dev @reticular/speakable

GitHub Actions

Add this workflow to run accessibility checks on every push. The audit step catches issues, and the diff step detects regressions against a baseline.

.github/workflows/a11y.yml

name: Accessibility Check

on: [push, pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - run: npm ci

      - name: Run accessibility audit
        run: npx @reticular/speakable ./dist/index.html -f audit

      - name: Check for regressions
        run: npx @reticular/speakable ./dist/index.html --diff ./baseline.html -f text

GitLab CI

.gitlab-ci.yml

accessibility:
  stage: test
  image: node:18
  script:
    - npm ci
    - npx @reticular/speakable ./dist/index.html -f audit
    - npx @reticular/speakable ./dist/index.html --diff ./baseline.html -f text

Exit Codes

Use exit codes in CI to fail builds on regressions or errors.

Code	Meaning
0	Analysis completed successfully, no regressions
1	User error — invalid arguments or options
2	Content error — accessibility issues found, or diff detected changes
3	System error — file not found, I/O failure

JSON Output

Use -f json to get machine-readable output for programmatic comparison:

JSON Output

{
  "version": { "major": 1, "minor": 0 },
  "root": {
    "role": "button",
    "name": "Submit",
    "state": {},
    "focus": { "focusable": true },
    "children": []
  },
  "metadata": {
    "extractedAt": "2026-04-02T12:00:00Z"
  }
}

Baseline Workflow

Save a baseline of your current accessibility state, then compare against it after making changes. This is the recommended workflow for regression detection.

Step 1 — Save baseline

# Save the current accessibility model as a baseline
speakable page.html -f json -o baseline.json

Step 2 — Make changes and compare

# After making HTML changes, diff against the baseline
speakable page.html --diff baseline.html

# Or get text-formatted diff output
speakable page.html --diff baseline.html -f text

Step 3 — Automate in CI

# In your CI pipeline, fail on regressions
npx @reticular/speakable ./dist/index.html --diff ./baseline.html || echo "Accessibility regression detected"

Commit baseline.html to your repository. When the diff detects changes, the CLI exits with code 2, which fails the CI step. Update the baseline intentionally when accessibility changes are expected.