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

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+# PR gate for the composite action. Keeps action.yml + example/workflow YAML
+# structurally valid on every change so a broken action can't merge.
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate YAML is well-formed
+        shell: bash
+        run: |
+          set -euo pipefail
+          for f in action.yml examples/*.yml .github/workflows/*.yml; do
+            python3 -c "import sys,yaml; list(yaml.safe_load_all(open('$f')))" \
+              && echo "ok: $f" || { echo "invalid YAML: $f"; exit 1; }
+          done
+
+      - name: Validate action.yml structure
+        shell: bash
+        run: |
+          set -euo pipefail
+          test -f action.yml || { echo "action.yml missing"; exit 1; }
+          for key in name description runs inputs outputs; do
+            grep -qE "^${key}:" action.yml || { echo "action.yml missing '${key}:'"; exit 1; }
+          done
+          grep -qE "using: 'composite'|using: composite" action.yml \
+            || { echo "action.yml must be a composite action"; exit 1; }
+          echo "action.yml is structurally valid."

.github/workflows/release.yml

@@ -0,0 +1,76 @@
+# Release pipeline for the BrowserStack Accessibility DevTools Action.
+#
+# v1 is a composite action (action.yml) that shells out to bash + the published
+# CLI, so there is nothing to bundle yet. This pipeline is a STUB that:
+#   - builds any bundled `dist/` if/when the action gains JS entrypoints (esbuild),
+#   - verifies action.yml is valid,
+#   - documents the (manual, admin-only) Marketplace publish step.
+#
+# Marketplace publishing needs a GitHub ORG ADMIN and is intentionally NOT
+# automated here (see the "publish" job note below).
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version tag (e.g. v1.0.0)'
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # Bundle a dist/ IF the action grows JS entrypoints (esbuild pattern).
+      # Guarded so the stub is a no-op for the current pure-composite action.
+      - name: Build bundled dist (esbuild)
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ -f package.json ] && jq -e '.scripts.build' package.json >/dev/null 2>&1; then
+            npm ci
+            # Example bundling target for a future JS action entrypoint:
+            #   npx esbuild src/index.ts --bundle --platform=node \
+            #     --target=node20 --outfile=dist/index.js
+            npm run build
+            echo "Bundled dist/ produced."
+          else
+            echo "No package.json build script — pure composite action, nothing to bundle."
+          fi
+
+      - name: Validate action.yml
+        shell: bash
+        run: |
+          set -euo pipefail
+          test -f action.yml || { echo "action.yml missing"; exit 1; }
+          # Minimal structural sanity: required top-level keys present.
+          for key in name description runs inputs outputs; do
+            grep -qE "^${key}:" action.yml || { echo "action.yml missing '${key}:'"; exit 1; }
+          done
+          echo "action.yml looks structurally valid."
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Marketplace publish (manual, org-admin only)
+        shell: bash
+        run: |
+          echo "GitHub Marketplace publishing is a MANUAL step and requires a GitHub org admin."
+          echo "Steps (performed in the GitHub UI by an admin):"
+          echo "  1. Draft a release for the pushed tag."
+          echo "  2. Tick 'Publish this Action to the GitHub Marketplace'."
+          echo "  3. Select category (Code quality / Utilities), accept the agreement, publish."
+          echo "This job is a placeholder and does not publish automatically."

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+*.log
+.DS_Store
+.env
+# Bundled output is produced by the release pipeline when/if JS entrypoints land.
+dist/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrowserStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,166 @@
-# browserstack-accessibility-devtools-action
-A package to support Accessibility Devtools Action
+# BrowserStack Accessibility for GitHub
+
+Catch accessibility issues on your pull requests. Comment
+**`@AccessibilityDevTools`** on a PR and BrowserStack scans the changed code,
+then posts the findings right back on the PR — as a summary comment, inline
+suggestions, and an optional merge check.
+
+- 🔎 **Scans only what changed** in the PR (fast, even on large repos).
+- 💬 **Results on the PR** — a summary comment and inline, one‑click suggestions.
+- ✅ **Optional merge gate** — fail the check when accessibility errors are found.
+- 🤖 **Optional agent hand‑off (preview)** — the findings comment can `@mention` a PR
+  agent you already use, which then acts under _your_ credentials. BrowserStack runs no
+  AI model and never handles your AI keys. **v1 is scan + report**; whether the agent
+  reviews or fixes is up to that agent (see "Optional: agent hand-off" below for what
+  works today).
+
+Learn more: <https://browserstack.com>
+
+---
+
+## Prerequisites
+
+1. **Install the BrowserStack Accessibility GitHub App** on your organization or
+   repository (a one‑time step, done by a repo/org admin).
+2. **Add a BrowserStack Service Account key** as repository or organization
+   **Actions secrets**:
+   - `BROWSERSTACK_USERNAME`
+   - `BROWSERSTACK_ACCESS_KEY`
+
+   A Service Account is a non‑personal, admin‑managed key built for CI — it uses
+   no user license and can be rotated or revoked independently. (Enterprise plan.)
+
+## Quick start
+
+Add `.github/workflows/browserstack-a11y.yml`:
+
+```yaml
+name: BrowserStack Accessibility
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read # read the PR's changed files
+  pull-requests: read # resolve the PR
+  id-token: write # prove the run came from your CI (required)
+
+concurrency:
+  group: a11y-${{ github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  a11y:
+    # Fires on a PR comment mentioning @AccessibilityDevTools. The action then verifies
+    # the commenter has write/maintain/admin permission before scanning.
+    if: >
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '@AccessibilityDevTools')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      # @v1 tracks the latest v1.x; pin to a full commit SHA for supply-chain hardening.
+      - uses: browserstack/browserstack-accessibility-devtools-action@v1
+        with:
+          username: ${{ secrets.BROWSERSTACK_USERNAME }}
+          access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
+          comment: true
+          check-gate: true
+          fail-on-severity: error
+```
+
+A ready-to-copy version lives at [`examples/browserstack-a11y.yml`](examples/browserstack-a11y.yml).
+
+Then, on any pull request, comment:
+
+```
+@AccessibilityDevTools
+```
+
+The scan runs and results appear on the PR within a couple of minutes.
+
+## How it works
+
+1. You comment **`@AccessibilityDevTools`** on the PR.
+2. The workflow runs BrowserStack's accessibility CLI against the PR's changed
+   files, authenticated by your Service Account key.
+3. Results are posted back to the PR **by the BrowserStack Accessibility App**
+   (a branded bot), so your workflow's default token never needs write access.
+
+> **Why `id-token: write`?** GitHub mints a short‑lived, repo‑scoped OpenID
+> Connect token that proves the request genuinely came from this repository's CI
+> run. BrowserStack verifies it before posting. It carries **no** personal
+> identity and grants no standing access.
+
+## Inputs
+
+| Input                | Default  | Description                                                                                                                              |
+| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `username`           | —        | **Required.** Service Account username (store as a secret).                                                                              |
+| `access-key`         | —        | **Required.** Service Account access key (store as a secret).                                                                            |
+| `comment`            | `true`   | Post a summary findings comment on the PR.                                                                                               |
+| `check-gate`         | `true`   | Publish a Check Run / commit status for the PR.                                                                                          |
+| `fail-on-severity`   | `error`  | Fail the check at this severity and above: `error`, `warning`, or `none`.                                                                |
+| `inline-suggestions` | `false`  | Add one‑click suggestion blocks on offending lines.                                                                                      |
+| `sarif`              | `false`  | Publish results to GitHub code scanning (Security tab). Uploaded by the App server-side — your workflow token needs no extra permission. |
+| `comment-mode`       | `update` | `update` a single sticky comment across runs, or post a `new` one each time.                                                             |
+| `remediation`        | `false`  | Enable the optional agent hand‑off (preview; see below).                                                                                 |
+| `ai-agent`           | —        | Required when `remediation: true`. The agent's name (e.g. `coderabbitai`, `claude`); we @‑mention it.                                    |
+
+## Outputs
+
+| Output           | Description                          |
+| ---------------- | ------------------------------------ |
+| `result`         | `pass` or `fail`.                    |
+| `error-count`    | Number of error‑severity findings.   |
+| `warning-count`  | Number of warning‑severity findings. |
+| `findings-count` | Total findings.                      |
+| `comment-url`    | Link to the posted PR comment.       |
+| `sarif-file`     | Path to the SARIF file (if enabled). |
+
+## Optional: agent hand‑off (preview)
+
+Set `remediation: true` and name your agent with `ai-agent`. When findings are
+posted, the App `@mentions` that agent on the PR (for example, `@coderabbitai`), and
+**your** agent acts under **your** credentials and billing.
+
+```yaml
+with:
+  username: ${{ secrets.BROWSERSTACK_USERNAME }}
+  access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
+  remediation: true
+  ai-agent: coderabbitai # BrowserStack posts "@coderabbitai"
+```
+
+What works today (honest status — this is a preview, off by default):
+
+- BrowserStack **runs no AI model and never stores your AI credentials.**
+- The agent must accept a trigger from a **bot/App** comment.
+  - **CodeRabbit** — responds to the mention, but produces a **review**, not a fix PR.
+  - **Claude** (`claude-code-action` / Anthropic Claude GitHub App) — a genuine fix
+    path, but **not yet reliable** for bot-authored triggers (upstream issues; being
+    validated). Treat as experimental.
+  - **GitHub Copilot's coding agent** — **not supported** (it only acts on comments from
+    a human with write access).
+- If your agent ignores bot authors by default, allow‑list the **BrowserStack
+  Accessibility** bot in its config.
+
+> **v1 is scan + report.** A guaranteed AI-_fix_ path is not part of v1; the hand-off
+> above is a preview and is a **silent no-op** if the agent isn't configured to accept it.
+
+## Privacy & security
+
+- Uses a **Service Account** key (not a personal login); store it as an encrypted
+  Actions secret and rotate via your admin.
+- The App's credentials stay on BrowserStack's side — they are **never** placed on
+  your runner.
+- The scan reads only the pull request's changed files.
+
+## Support
+
+- Product & docs: <https://browserstack.com>
+- Accessibility API reference (including rate limits): <https://www.browserstack.com/docs/accessibility/api>
+
+## License
+
+[MIT](LICENSE)