theaccessible-audit-ci

CLI for TheAccessible CI/CD integration. Grades a target (URL, build artifact, or VPAT file) against WCAG 2.1 AA / Section 508 and emits a stored, queryable compliance record per commit.

Install

npm install -g theaccessible-audit-ci

Authenticate

Create an audit API key at https://theaccessible.org/settings/api-keys, scope it to a single GitHub-style owner/repo, then set:

export THEACCESSIBLE_API_KEY="tac_…"

The CLI never logs the raw key — it's masked in all stderr output (tac_xy…wxyz). Override the API host with THEACCESSIBLE_API_URL if you're using a self-hosted deployment.

Configure

Drop a .theaccessible.yml at your repo root:

version: 1
targets:
  - name: marketing-site
    type: url
    url: https://staging.theaccessible.org
  - name: pdf-app-build
    type: build-artifact
    path: ./apps/web/dist
gate:
  mode: advisory          # advisory | blocking
  min_grade: B            # A | B | C | D | F
  fail_on: []             # new_critical_issues | grade_regression | min_grade_violation
notifications:
  email:
    digest: weekly
    recipients: [[email protected]]
timeout_seconds: 300

gate.mode defaults to advisory on first install. Advisory mode prints warnings and exits 0, so installing the CLI never breaks a green build. Switch to blocking only after your team has reviewed a few runs and agreed on which gates to enforce.

Commands

theaccessible audit [target]              # run an audit (default: first target)
theaccessible diff <base-sha> <head-sha>  # show regression delta between two prior runs
theaccessible report <commit-sha>         # fetch stored reports for a commit

audit options

| Flag | Default | Notes | | -------------------------- | ---------------------- | -------------------------------------------------- | | --config <path> | .theaccessible.yml | Path to config | | --output-dir <dir> | ./.theaccessible | Writes audit-report.json + .sarif | | --timeout-seconds <n> | gate.timeout_seconds | Sync poll budget; falls back to async beyond this | | --fail-on <reasons> | gate.fail_on | Comma-separated override |

Exit codes

| Code | Meaning | | ---- | ----------------------------------------------------------------------------------------------- | | 0 | Pass (including advisory-mode "would-have-failed" cases) | | 1 | Accessibility gate failed in blocking mode | | 2 | Tool / network / auth error (treat differently from 1 in CI — don't blame the code) |

Distinguish these in your CI step:

- run: theaccessible audit
  continue-on-error: ${{ inputs.gate-mode == 'advisory' }}

Outputs

After every audit run you get three artifacts:

• stdout — human-readable grade + top regressions.
• ./.theaccessible/audit-report.json — full machine-readable result.
• ./.theaccessible/audit-report.sarif — SARIF 2.1.0 for GitHub code-scanning annotations.

Git context auto-detection

The CLI pulls commit_sha, branch, repo, and actor from CI env vars (GITHUB_SHA, GITHUB_REF_NAME, GITHUB_REPOSITORY, GITHUB_ACTOR, and the equivalent GitLab CI_* vars), falling back to git rev-parse locally. The audit endpoint is idempotent on (repo, commit_sha, target.name) — re-running the same commit returns the existing job and never re-bills.

Generic CI recipes

See docs/ci-integration.md for GitLab CI, CircleCI, Jenkins, and Bitbucket Pipelines snippets.