Developer quick start

Run automated accessibility checks locally or in GitHub Actions using the MIT-licensed @gatekeeperqa/cli@0.1.1. Use Node.js 24. You do not need access to GatekeeperQA's source repository or a hosted scanner account. Local and CI execution do not consume public web scanner allowances.

1. Install the published CLI

From your application's directory (with an existing package.json):

npm install --save-dev --save-exact @gatekeeperqa/cli@0.1.1
npx --no-install playwright install chromium

For an empty directory, run npm init -y first. On a Linux CI runner, install Chromium with system dependencies using npx --no-install playwright install --with-deps chromium.

2. Choose the pages and policy

Create gatekeeperqa.json:

{
  "urls": ["http://127.0.0.1:3000/"],
  "failOn": ["critical", "serious"],
  "warnOn": ["moderate", "minor", "unknown"],
  "timeoutMs": 30000
}

Start your application and wait until it is ready. Replace the URL with a page you own or have permission to test. The CLI scans 1–20 explicit HTTP(S) URLs; it does not crawl the site. URLs containing credentials, query strings or fragments are rejected. Login flows, interactions and custom readiness checks are not supported.

3. Scan and read the result

npx --no-install gatekeeperqa --config gatekeeperqa.json --output reports

Open reports/report.html for the readable report. Other outputs are report.json, report.md, and report.xml (JUnit). The CLI does not directly export PDF; PDF is available through the browser interfaces.

An incomplete page cannot produce a passing gate. Disabling severity thresholds does not suppress execution failures or unresolved-check warnings. Use a fresh output directory in automation: an unsuccessful run must not be confused with reports from an earlier run.

4. Run a deployed-page check in GitHub

Copy Download accessibility.yml into your repository as .github/workflows/accessibility.yml. The complete copy-ready workflow is below. It installs the published package, saves reports before enforcing the gate, and requires only read access.

After committing it to your default branch, open Actions → Accessibility check → Run workflow, enter an authorized public page URL, and run it. No GatekeeperQA API key is required.

name: Accessibility check
on:
  workflow_dispatch:
    inputs:
      target_url:
        description: Public URL you own or are authorized to test
        required: true
        type: string
permissions:
  contents: read
jobs:
  accessibility:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: '24'
      - name: Install scanner
        working-directory: ${{ runner.temp }}
        run: |
          mkdir gatekeeperqa
          cd gatekeeperqa
          npm init -y
          npm install --save-exact @gatekeeperqa/cli@0.1.1
          npx --no-install playwright install --with-deps chromium
      - name: Scan authorized URL
        id: scan
        working-directory: ${{ runner.temp }}/gatekeeperqa
        env:
          SCAN_URL: ${{ inputs.target_url }}
        shell: bash
        run: |
          node -e 'require("fs").writeFileSync("gatekeeperqa.json",JSON.stringify({urls:[process.env.SCAN_URL]}))'
          set +e
          npx --no-install gatekeeperqa --config gatekeeperqa.json --output reports
          result=$?
          set -e
          echo "exit-code=$result" >> "$GITHUB_OUTPUT"
          if [ "$result" -eq 2 ]; then
            mkdir -p reports
            echo "Scanner setup or configuration failed. No passing result issued." > reports/error.txt
          fi
      - name: Save reports
        if: ${{ always() && steps.scan.outputs.exit-code != '' }}
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: accessibility-reports
          path: ${{ runner.temp }}/gatekeeperqa/reports
          retention-days: 7
          if-no-files-found: error
      - name: Enforce result
        if: ${{ always() }}
        env:
          RESULT: ${{ steps.scan.outputs.exit-code }}
        run: |
          case "$RESULT" in
            0) exit 0 ;;
            1) echo "Accessibility gate failed. Review the reports."; exit 1 ;;
            *) echo "Scanner did not complete successfully."; exit 2 ;;
          esac

Find the report after a failure

Open the workflow run and download accessibility-reports from Artifacts. Unzip it and open report.html. JSON, Markdown and JUnit files are included for completed scans. For setup/configuration errors, inspect the failed step's log and error.txt if present. If installation failed before scanning, there may be no artifact. Retention is seven days.

The workflow intentionally uploads evidence before failing the job. Do not add continue-on-error to a production quality gate.

Adapt it for pull requests

The workflow above is a manual check of a deployed URL, not a check of changed PR code. For PR validation, add a pull_request trigger and either start the checked-out application on the runner or use that PR's deployed preview URL. Wait for readiness before scanning. A scan of your existing production site does not validate un-deployed PR changes.

Use read-only repository permissions, avoid pull_request_target for untrusted code, and do not expose secrets to fork PRs. Configure the resulting check as required in repository branch protection or rulesets if it should block merging. Reports may contain page content; choose targets and artifact visibility accordingly.

Scope and limitations

The published npm release is version 0.1.1. Later hosted reporting changes are not automatically included. Automatic PR comments are not implemented. Automated checks support human assessment; PASS is a configured quality-gate result, not full WCAG or Section 508 conformance.