feat(DEVA11Y-657): composite GitHub Action (v1 scan+report)

[Crash0v3rrid3]

DEVA11Y-657 — Composite GitHub Action (v1: scan + report)

Ships the public composite Action for the CI/CD accessibility flow (Epic DEVA11Y-463, ADR-0035/0036).

A developer comments @AccessibilityDevTools on a PR → this Action runs the published @browserstack/accessibility-devtools CLI in PR-scan mode, authenticated by a BrowserStack Service Account key (zero GitHub credentials on the runner) → the CLI sends findings to linter-server, which normalizes + HMAC-signs them (scanProof) → the runner forwards {report, scanProof} (plus a best-effort Actions OIDC token) to the ci-review-service, which verifies and posts as the GitHub App.

What's in this PR

• action.yml — composite Action with the ADR-0035 Appendix A input surface (username, access-key, comment, check-gate, fail-on-severity, inline-suggestions, sarif, comment-mode, remediation, ai-agent) and outputs (result, error-count, warning-count, findings-count, comment-url, sarif-file).
• examples/browserstack-a11y.yml — reference consumer workflow (on: issue_comment, permissions: contents/pull-requests read + id-token write).
• .github/workflows/release.yml — versioned release/bundle pipeline (SHA-pinned CLI, tagged dist).
• README.md, LICENSE, .gitignore.

Fork-PR safety

"Diff, don't build" — no npm install/postinstall of untrusted head code; degrades to skip when OIDC/secrets are restricted.

Status / dependencies

• Draft — depends on the linter-server + CLI (a11y-linter #406, story DEVA11Y-655) and ci-review-service (a11y-linter #407, story DEVA11Y-656) landing, plus the real GitHub App credentials + Marketplace listing.
• CLI version pin / Marketplace publish to be finalized before GA.

🤖 Generated with Claude Code

[Crash0v3rrid3]

Code review

Reviewed the composite action (bugs + security; no CLAUDE.md in this repo). Found 1 functional issue — now fixed in 222bd37:

1. Commenter permission gate hard-failed under the documented read-only token (P1). GET /repos/{owner}/{repo}/collaborators/{username}/permission requires push access; the recommended least-privilege workflow token (contents: read, pull-requests: read) cannot call it, so it 403'd, the || echo none fallback resolved to none, and the action refused to scan for every commenter — non-functional under its own recommended setup.

   Fix: the client-side check is now best-effort — it fast-refuses only on a definitive non-privileged role and, on an inconclusive call (the read-only-token case), proceeds and defers to the authoritative server-side fail-closed permission gate in the ci-review-service (ADR-0035 §5). The runner is the customer's and was never the security boundary.

   browserstack-accessibility-devtools-action/action.yml

   Lines 160 to 172 in 222bd37

   	# read-only token the call fails (gh exits non-zero) and we must NOT refuse.
   	if perm="$(gh api "repos/${repo}/collaborators/${actor}/permission" --jq '.permission' 2>/dev/null)"; then
   	echo "Commenter ${actor} has permission: ${perm}"
   	case "$perm" in
   	admin|maintain|write)
   	echo "allowed=true" >> "$GITHUB_OUTPUT" ;;
   	*)
   	echo "::warning::${actor} lacks write/maintain/admin permission; refusing to scan."
   	echo "allowed=false" >> "$GITHUB_OUTPUT" ;;
   	esac
   	else
   	# Could not read the commenter's permission (expected with the documented
   	# read-only GITHUB_TOKEN, which cannot call the collaborators API). Do not

Also corrected the preflight fork-safety comments: issue_comment workflows run in base-repo context with secrets available even for fork PRs, so cred-absence is not what protects fork PRs — the permission gate + "diff, don't build" (no PR-head-code execution) are.

Verified clean: OIDC request URL separator (&audience= onto GitHub's already-?-bearing request URL), jq --argjson prNumber body assembly, composite-step failure propagation (scan failure skips oidc/submit; the always() report step fails closed), and no ${{ github.event.* }} interpolated into any run: block (all untrusted input routed via env + jq over GITHUB_EVENT_PATH). All YAML parses; the validate-action structural checks pass.

No remaining high-confidence issues.

Verdict: PASS (draft — placeholders for CLI version, service URL/audience, and the pinned action SHA remain, as expected pre-GA).

🤖 Generated with Claude Code

[aveek-bs]

1. Overall the document seems to guide users to @/mention AccessibilityDevtools manually - rather we want to guide users to setup the automatic violation detection flow (with manual commenting as the secondary flow). Please see how you can rework the Prerequisites , Quick start and How it works
2. comment-mode input - can we have a more intuitive name for this?
3. inline-suggestions and sarif inputs - The readme should emphasize that the latter being true is a pre-requisite for enabling the former.

[aveek-bs]

Also, the output message formatting should follow the same format as the VS Code formatting

(label): <description>

<how_to_fix>

[Crash0v3rrid3]

Thanks @aveek-bs — both of your points are addressed in the latest push:

1. Automatic detection flow (primary), manual @mention secondary. The example workflow and README now lead with on: pull_request (opened/synchronize/reopened/ready_for_review) as the primary trigger; commenting @AccessibilityDevTools is documented as the on-demand secondary path. On the automatic path the action resolves the PR author as the actor (no commenter gate); the server-side fail-closed permission gate still applies before anything is posted.

2. VS Code output format. Findings now render as (rule): <description> followed by the how-to-fix text — matching the VS Code extension — in both the summary comment and the inline comments (implemented in ci-review-service render.ts, browserstack-a11y-linter#421).

While here, from a full audit of the inputs (your "are we supporting all of these?" note): the surface is now trimmed to the inputs that actually do something — username, access-key, fail-on-severity, and optional ai-agent. Posting a summary comment, inline comments, a Check Run, and SARIF upload are always-on server defaults. And fail-on-severity now genuinely gates the run (previously --pr-scan always exited 0, so the check never failed regardless of the setting). SARIF is now actually generated + uploaded, and inline comments are deduped across re-runs.