GitHub Action

The frontend-debugger-action runs a full audit on any URL directly inside your GitHub Actions workflow — no server setup required.

Quick start

# .github/workflows/audit.yml
name: Frontend Audit
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: starkyru/frontend-debugger-action@main
        with:
          url: 'https://your-preview-url.example.com'

What is "your preview URL"?

The url input is the address of the page you want to audit. In CI this is typically:

Scenario	Example URL
Vercel PR preview	https://my-app-git-pr-123.vercel.app
Netlify deploy preview	https://deploy-preview-42--mysite.netlify.app
Staging server	https://staging.myapp.com
App started in CI	http://localhost:3000

The action launches a headless Chrome, navigates to that URL, and runs all configured checks.

Inputs

Input	Default	Description
url	required	URL to audit
format	html	Report format: html, junit, or sarif
report-path	auto	Output path for the report file
chrome-port	9222	Chrome remote debugging port
skip-a11y	false	Skip accessibility audit
skip-contrast	false	Skip contrast check
skip-aria	false	Skip ARIA validation
tokens-file	—	Path to design tokens JSON
diff-name	—	Baseline name for visual diff
post-pr-comment	true	Post summary comment on the PR
github-token	github.token	Token for posting PR comments
fail-on-violations	true	Exit non-zero on violations
host-url	—	URL of a self-hosted reports server (see Hosted reports)

Outputs

Output	Description
violations-count	Total number of violations found
report-url	Shareable link to the report (hosted server or artifact URL)

Hosted reports

By default the HTML report is uploaded as a GitHub Actions artifact (expires after 90 days, requires login to view).

If you run fd-host (the self-hosted reports server), set host-url to get a permanent, shareable link:

- uses: starkyru/frontend-debugger-action@main
  with:
    url: ${{ steps.deploy.outputs.preview-url }}
    host-url: 'https://reports.uiprobe.dev'
  env:
    FD_HOST_TOKEN: ${{ secrets.FD_HOST_TOKEN }}

The action will POST the HTML report to your server and write the stable URL to the report-url output and to the PR comment.

PR comment

When post-pr-comment: true (default), the action upserts a comment on the pull request with a summary table and a link to the full report:

## Frontend Debugger Audit
| Check   | Status              |
|---------|---------------------|
| Overall | ❌ 3 violation(s)   |

[View full report](https://reports.uiprobe.dev/r/abc-123)

Full workflow example — PR preview with hosted reports

name: Audit PR preview
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Deploy your app to get a preview URL (example: Vercel)
      - name: Deploy preview
        id: deploy
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}

      # Audit the preview URL and post results to the PR
      - name: Audit
        uses: starkyru/frontend-debugger-action@main
        with:
          url: ${{ steps.deploy.outputs.preview-url }}
          host-url: 'https://reports.uiprobe.dev'
          format: sarif
        env:
          FD_HOST_TOKEN: ${{ secrets.FD_HOST_TOKEN }}

      # Also upload SARIF for GitHub Code Scanning annotations
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: fd-audit-report.sarif
          category: frontend-debugger

SARIF — inline PR annotations

Use format: sarif to get violations as inline annotations on the PR diff:

- uses: starkyru/frontend-debugger-action@main
  with:
    url: ${{ env.PREVIEW_URL }}
    format: sarif

The action automatically uploads the SARIF file to GitHub Code Scanning.

JUnit — test reporting

Use format: junit to integrate with CI test reporters (Jenkins, CircleCI, etc.):

- uses: starkyru/frontend-debugger-action@main
  with:
    url: ${{ env.PREVIEW_URL }}
    format: junit
    report-path: test-results/frontend-audit.xml

Self-hosted reports server

To deploy your own reports server, see the fd-host package. A public instance is available at https://reports.uiprobe.dev.