Accessibility testing with CLI and GitHub Actions

Developer guide: CLI and GitHub Actions

This guide covers Gatekeeper Q A from the command line and in GitHub Actions. We will configure an explicit page, inspect a failing result, fix a button label, and retrieve a successful retest. Browser captures are from real runs. Command cards are readable instructions; local result cards summarize retained execution logs. Narration is synthetic.

1. Install the pinned CLI

Use Node J S twenty four with N P M. In a new project directory, initialize package dot J S O N, install Gatekeeper Q A C L I version zero point three point zero, then install Playwright Chromium. In an existing project, skip N P M init. The clean GitHub runner installation shown later also verifies this published package.

node --version
npm init -y
npm install --save-dev --save-exact @gatekeeperqa/cli@0.3.0
npx --no-install playwright install chromium

2. Start your app and configure pages

Start your application using its normal development command, and wait until its page is available. Save gatekeeper Q A dot J S O N with the actual U R L. This example uses localhost port three thousand. Replace that address if your app uses another port. The C L I checks explicit U R Ls, not a whole-site crawl.

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

3. Run a baseline scan

Run the C L I with your configuration and a separate before output directory. Open report dot H T M L after the command finishes. In our local demonstration, the unnamed button produced a critical button-name finding and exit code one. The retained transcript records that real result; the equivalent N P X command is shown here.

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

Recorded local result (CLI build 0.3.0):
GatekeeperQA: FAIL
Exit code: 1
button-name · critical · 1 affected occurrence

4. Read reports and exit codes

The C L I writes H T M L, J S O N, Markdown and J Unit X M L. It does not directly produce a P D F. Exit zero means the configured gate did not fail, and can include a warning. Exit one indicates a gate or execution failure. Exit two indicates setup or configuration trouble. Always read the report.

reports/before/report.html
reports/before/report.json
reports/before/report.md
reports/before/report.xml

Bash: echo $?     PowerShell: $LASTEXITCODE

5. Fix, then preserve a separate retest

Give the button meaningful visible text and run the same scope into an after directory. Our local retest returned pass and exit zero. Preserve the baseline. Reproduce the affected page state and test the interaction manually, including a screen reader. A passing automated result does not prove the entire experience is accessible.

Before: <button id="checkout"></button>
After:  <button id="checkout">Checkout</button>

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

Recorded local result: PASS · exit 0

6. Add the manual GitHub workflow

Copy the downloadable accessibility workflow into dot github slash workflows slash accessibility dot Y A M L in your repository. Commit it to the default branch so Run workflow is available. The template uses a manual trigger, read-only repository permission, Node twenty four, the pinned C L I, and seven-day report artifacts. It does not deploy your application.

.github/workflows/accessibility.yml

Trigger: workflow_dispatch
Input: target_url
Install → Scan → Save reports → Enforce result

Use a public deployed page you are authorized to test.

7. Choose the branch and public target

Open Actions, select the workflow, and choose Run workflow. Select the branch containing your intended workflow version and enter an authorized public page. Our recording uses an existing verification workflow on the review branch, with C L I zero point three point zero. The downloadable template has the same scan and artifact steps, with a manual trigger.

8. Inspect a genuine failed gate

The first GitHub run failed on the original demonstration page. Expand Scan authorized U R L and Enforce result to see the result and exit code. Save reports runs before the gate is enforced, so a failed accessibility result still leaves evidence. Open the artifact on the run summary rather than relying on the red status alone.

9. Retrieve the fixed-page result

After publishing the button fix, we ran the same workflow and public U R L again. This run succeeded, with one report artifact. Open the accessibility job for its scan output, then download accessibility reports from the summary. Extract the archive and open report dot H T M L; retain the machine-readable files for your tools.

10. Keep the evidence after the runner stops

The saved artifact contains the generated report files. Download it before its seven-day retention ends. The runner installed the public N P M package and Chromium cleanly; the two recorded runs took fifty four and forty one seconds. Check your own GitHub plan for runner billing. A completed job proves this run, not every page or state.

11. Adapt CI carefully

For pull-request testing, first build and start the changed application on the runner, or deploy a preview and wait for it. Point the scan at that changed version. A manual scan of production is not a pull-request check. Add the appropriate trigger and branch protection deliberately. This guide does not configure a P R bot or automatic comments.

Before enforcing pull-request checks:
1. Build and start the changed application.
2. Wait until its URL is ready.
3. Scan that URL and preserve reports.
4. Enforce the result after artifact upload.
5. Configure required checks for your repository.

Use automation and human review together

You now have a repeatable C L I and Actions workflow: explicit scope, a clear gate, report artifacts, and a separate retest. Use the browser tester guide to record manual observations and compare saved reports. Download the workflow and read the developer quick start on gatekeeper Q A dot com. Keep human testing part of every release.